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Preface 



Host versions 

The documentation set which accompanies the Occam 2 tooiset is designed to 
cover all host versions of the toolset: 

• iMS D7305 - IBM PC compatilJle running MS-DOS 

• IMS D4305 - Sun 4 systems running SunOS. 
■ IMS D6305 - VAX systems running VMS. 

About this manuai 

This manual is the Language and Libraries Reference Manual to the Occam 2 
toolset and provides a language reference for the toolset and implementation data. 

The larger part of the manual is contained in one chapter which introduces and 
describes the occam libraries. Each library is described in a separate section. For 
each library, a summary of the procedures it provides, is followed by a detailed 
description of each procedure. 

Appendices provide: 

• a description of the language extensions that are supported by the Occam 
2 compiler 

• implementation details of the Dx305 occam 2 toolset. 

• details of the alias and usage checking mies adopted by the toolset 
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viii About the toolset documentation set 



About the toolset documentation set 

The documentation set comprises the following volumes: 

• 12 IDS 366 01 Occam 2 Toolset User Guide 

Describes the use of the toolset in developing programs for running on the 
transputer. The manual is divided into two sections; 'Basics' which 
describes each of the main stages of the development process and 
includes a 'Getting started* tutorial. The 'Advanced Techniques' section is 
aimed at more experienced users. The appendices contain a glossary of 
terms and a bibliography. Several of the chapters are generic to other 
IN MOS toolsets. 

• 72 TDS 367 01 Occam 2 Toolset Reference Manual 

Provides reference material for each tool in the toolset including command 
line options, syntax and error messages. Many of the tools in the toolset 
are generic to other INMOS toolset products, e.g. the ANSI C and 
FORTRAN toolsets, and the documentation reflects this -examples may 
be given in more than one language. The appendices provide details of 
toolset conventions, transputer types, the assembler, server protocol, 
ITERM files and bootstrap loaders. 

• 72 TDS 368 01 oocam 2 Toolset Language and Libraries Reference 
Manual {ih\s manual) 

• 72 TDS 3 79 00 Performance Improvement with the INMOS Dx305 Occam 
2 Toolset 

This document provides advice about how to maximize the performance 
of the toolset. It brings together inforniation provided in other toolset docu- 
ments particulariy from the Language and Libraries Reference Manual. 
Note: details of how to manipulate the software virtual through-routing 
mechanism are given In the User Guide. 

• 72 TDS 377 00 OCCam 2 Toolset Handbook 

A separately bound reference manual which lists the command line 
options for each tool and the library functions. It is provided for quick refer- 
ence and summarizes information provided in more detail in the Tools 
Reference Manual and the Language and Libraries Reference ManuaL 

• 72 TDS 378 00 occam 2 Toolset Master Index 

A separately bound master index which covers the User Guide, Toolset 
Reference Manual, Language and Libraries Reference Manual and the 
Performance Improvement document. 
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Other documents 

Other documents provided with the toolset product include: 

• Delivery manuai giving instailation data, this document is host specific. 

• Release notes, common to ail host versions of the toolset 

• 'Occam 2 Reference Manual' published by Prentice Hail. 

• 'A Tutorial Introduction to Occam Programming' published by BSP Profes- 
sional Books. 

FORTRAN toolset 

At the time of writing the FORTRAN toolset product referred to in this document 
set is still under development and specific details relating to it are subject to 
change. 

Documentation conventions 

The following typographical conventions are used in this manual: 

Bold type Used to emphasize new or special terminology 

Teletype Used to distinguish command line examples, code fragments, 

and program listings from normal text. 
ttafjc type In command syntax definitions, used to stand for an argument 

of a particular type. Used within text for emphasis and for book 

titles. 
Braces { } Used to denote optional items in command syntax. 

Brackets [] Used in command syntax to denote optional items on the 
command line. 

Ellipsis , . , ingeneralterms.usedtodenotethecontlnuationofaseries.For 
example, in syntax definitions denotes a list of one or more 
items. 

I In command syntax, separates two mutually exclusive alterna- 

tives. 
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1 The Occam 
libraries 



1.1 Introduction 

A comprehensive set of Occam libraries is provided for use with the toolset. They 
include the compiler iibraries which the compiler iteetf uses, and a number of user 
tibraries to support common programming tasks. The compiler libraries are auto- 
matically referenced whereas user libraries must be declared in a #aSE directive. 
Libraries, including the compiler libraries, must be specified to the linker. Table 1.1 
lists the Occam libraries. 



Library 


Description 


Source 
provided 


Compiler libraries 


No 


occamjc.lib 


Multiple length integer arithmetic 

Floating point functions 

32"blt IEEE artthmetk; functions 

64-bit IEEE arithmetic functions 

2D block move libtaty 

Bit manipulation 

CRC functions 

Supplementary floating point support 

Dynamte code loading support 

Transputer-related functions 




User libraries 




flnglmath.lib 


Single length mathematical functions 


Yes 


dblmath,lib 


Double length mathematical functions 


Yes 


tbmaths.lib 


T400/T414/T425/T426 optimized maths 


Yes 


boatio . lib 


Host file server library 


Yes 


streamio.lib 


Stream I/O library 


Yes 


string . lib 


String handling library 


Yes 


convert, lib 


String conversion library 


Yes 


ore . lib 


Block CRC library 


Yes 


xlink.lib 


Extraordinary link handling library 


No 


debug. lib 


Debugging support library 


No 


msdos . lib 


DOS specific hostio library 


Yes 



Table 11 occam libraries 
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1.3 Compiler libraries 



1.2 Using the occam libraries 

User libraries must be declared in a #USE directive. For example: 

#USE "hostio.lib" 

Any use of a library routine must be in scope with the #asE directive which refer- 
ences the associated library. The scope of a library, like any Occam dedaration, 
depends on its level of indentation wittiin the text. 

If the library uses a file of predefined constants (see section 1.2.3) then this must 
be declared by an #INCLDD£ directive, before the associated #USE. For example: 

#INCLUDE "hostio,inc" 

1.2.1 Linking libraries 

All libraries used by a program or program module must be linked with the main 
program. This includes the compiler libraries even though they are automatically 
referenced by the compiler (see section 1 .3). 

1.2.2 Listing library contents 

You can use the ilist tool to examine the contents of a library and determine 
which routines are available. The tool displays procedural interfaces for routines 
in each library module and the code size and workspace requirements for indi- 
vidual modules. It can also be used to determine the transputer types and en'or 
modes for which the code was compiled. (See chapter 10 of the Occam 2 Toolset 
Reference Manual for details of ilist). 

1 .2.3 Library constants 

Constants and protocols used by the libraries are defined in six include files: 



File 


Description 


hostio.inc 


Constants for the host file server interface {hostio library) 


streamio . inc 


Constants for the stream i/o interface {streamio library) 


m^thvals . inc 


Maths constants 


linkaddr . inc 


Addresses of transputer links 


ticks , inc 


Rates of the two transputer clocks 


msdos . inc 


DOS specific constants 



Table 1 .2 Library constants 
Include files should always be declared before the related library. 
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1 The Occam libraries 



1.3 Compiler libraries 

Compiler libraries cxintain multiple length and floating point aritiimetic functions, 
IEEE functions, and special transputer functions such as bit manipulation and 2D 
block data moves. They are found automatically by the compiler on the path speci- 
fied by the ISEARCH host environment variable and do not need to be referenced 
by a #USE directive. Mowevefr they must be specified to the linker along with all 
other libraries that the program uses; this is best done using one of the linker indi- 
rect files occajii2 . InJc, occamS . Ink, or occama . Ink, which specify the correct 
libraries for the transputer target. 

Separate compiler libraries are supplied for different types and families of proces- 
sors. Processor types supported are: 

• T2femlly 

• T8 family 

• 32-bit processors 

The compiler selects the correct library for the transputer type specified. All en^or 
modes are supported in each library. 



File 


Processor types supported 


occaiii2.1ib 


T212yT222n'225/M212 


occamS . lib 


T800fT8O1/T805 


occama. lib 


T400/r414/r42&T426n-AA'B 


oncaiRTihl .lib 


All 


virtual . lib 


All 



occamutl . lib contains routines which are called from within some of the other 
compiler libraries and virtual. lib is used to support interactive debugging. 
These two libraries support all processor types and error modes. 

File names of the compiler libraries must not be changed. The compiler assumes 
these filenames, and generates an error if they are not found. (See section A.4 in 
the Occam 2 Tooiset Reference Manual for details of the mechanism for locating 
files.) 

The compiler 'E' option disables all of the compiler libraries except virtual , lib, 
which can be disabled by the 'Y' option. 

The Occam 2 Reference Manual contains formal descriptions of many of the 
compiler library routines. 

1.3.1 Using compiler library routines 

Although primarily intended for use by the compiler, some compiler library routines 
are available to the programmer. These are listed in sections 1.3.2 through 1.3.9. 
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1.3 Compiler libraries 



They can be called directly without referencing them via a #USE statement and are 
disabled by the compiler 'E' option. 

As an example of how they may be used, consider an application which requires 
compliance with the IEEE standards for NaNs {'Not a Number') and Infs ('± 
infinity'). The ocx;am compiler defaults to non-IEEE behavior i,e. NaNs and Infs 
are treated as en-ors, whereas ANSI/IEEE 754-1985 requires there to be en^or and 
overflow handling. To obtain IEEE behavior the appropriate compiler library func- 
tion must be called. 

The following code fragments show a simple addition can be implemented by 
default or using IEEE-compatible functions. 

Ef A, B, and C are R£AL32s and b is a BOOL: 



A := B + C 



default Occam behavior* 



A := REAL320P{B, 0, C) 



b, A := IEEE320P(B, 1, 0, C) 



IKEE fiinction, round 
to nearest only. The 
indicates a H' 
operation . 

IEEE function with 
rounding option. The 
1 indicates round to 
nearest. The 
indicates a H' 
operation. 



1.3.2 Maths functions 

The following table lists compiler library maths fundions available to the 
programmer Further details can be found in appendices K, L, and M of the Occam 
2 Reference Manual. 



Result(s) 


Function name 


Parameter specifiers 


R£AI,32 


ABS 


VAL REAL32 x 


REAI32 


SQRT 


VAL REAL32 x 


REAL32 


LOGB 


VAL REAL32 x 


INT, REAL32 


FLOATING. UNPACK 


VAL RRAL32 x 


REAL32 


MINUSX 


VAL REAL32 x 


I%EAL32 


MULBY2 


VAL REAL32 x 


PEAL32 


DIVBY2 


VAL REAL32 x 


REAL32 


FPINT 


VAL REAL32 x 
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1 The Occam libraries 



Resu]t(s) 


Function name 


Parameter specifiers 


BOOL 


ISKAN 


VAL REAL32 x 


BOOL 


NOTFINITE 


VAL REAL32 x 


REAL32 


RrAT.KR 


VAL REAL32 x, VAL INT n 


REAL32 


copysiGN 


VAL REAL32 x, y 


BSAL32 


NEXTAFTER 


VAL PEAL32 x, y 


BOOL 


ORDERm 


VAL REAL32 x^ y 


BOOL, 

INT32, 

REAL32 


ARGUMENT . REDUCE 


VAL REAL32 x, y, y.err 


PEAL32 


REJa320P 


VAL RKAL32 x, 
VAL INT op, 
VAL REAL32 y 


REAL32 


REAL32REM 


VAL REAL32 x, y 


B00XirREAL32 


IEEE320P 


VAL REAL32 x, 
VAL INT rm, op, 
VAL REAL32 y 


BOOL,K£AL32 


TEEE32BEM 


VAL REAL32 X, y 


BOOL 


REAL32EQ 


VAL FEAL32 x, y 


BOOL 


ri:al32gt 


VAL REAL32 x, y 


INT 


lEEECOHPARE 


VAL REAL32 x, y 


II£:AL64 


DABS 


VAL REAL64 x 


REAL64 


DSQRT 


VAL BEAL64 X 


R£AL64 


DLOGB 


VAL REAL64 X 


INT,REAL64 


DFLOATING. UNPACK 


VAL REALe4 x 


REAL64 


DMINUSX 


VAL REAL64 x 


It£AL64 


DMULBY2 


VAL REAL64 x 


REAL64 


DDIVBy2 


VAL REAL64 x 


REAL64 


DFPINT 


VAL BEAL64 x 


BOOL 


DISHAH 


VAL BEAL64 x 


BOOL 


DNOTFIHITE 


VAL REAL64 x 


REAL64 


DSCALEB 


VAL REAL64 x, VAL INT n 


REAL64 


DCOPYSIGN 


VAL REAL64 x, y 


REAL64 


DNEXTAFTER 


VAL REAL64 x, y 


BOOL 


DORDERED 


VAL REAL64 x, y 


BOOL, 

I1JT32, 

REALe4 


DARGUMEKT . REDUCE 


VAL REAL64 x, y, y,err 
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1.3 CompHer libraries 




Result(s) 


Function name 


Parameter specifiers 


REAL64 


REAL640P 


VAL FEAL64 x, 
VAL INT Op, 
VAL REAL64 y 


REAL64 


R£ALe4R£M 


VAL REAL64 x, y 


BOOL, REAL64 


IKKK640P 


VAL BEAL64 x, 
VAL INT rm, op, 
VAL RKAL64 y 


BOOL, REAL64 


IEEE64REM 


VAL BEAL64 x, y 


BOOL 


REAL64EQ 


VAL HEAL64 X, y 


BOOL 


REAL64GT 


VAL REAL64 x, y 


INT 


DIEEECOMPARE 


VAL HEAL64 x, y 


INT 


LONGADD 


VAL INT left, right, 
carry . in 


INT 


LONGSUM 


VAL INT left, right, 
carry . in 


INT 


T.ONGSDB 


VAL INT left, right, 
borrow . in 


INT; INT 


LONGDIFF 


VAL INT left, right, 
borrow, in 


INT, INT 


LONGPROD 


VAL INT loft, right, 
carry . in 


INT; INT 


LONGDIV 


VAL INT dividend. hi, 
dividend. lo , divisor 


INT; INT 


SHIFTLEFT 


VAL INT hi. in, lo.in; 
places 


INT; INT 


SHIFTRIGHT 


VAL INT hi. in, lo.in, 
places 


INT; INT, INT 


NORMALISE 


VAL INT hi. in, lo.in 


INT 


ASHIFTLEFT 


VAL INT argument, places 


INT 


ASHIFTRIGHT 


VAL INT argument, places 


INT 


ROTATELEFT 


VAL INT argiiment, places 


INT 


ROTATERIGHT 


VAL INT argument, places 



Notes 

SHIFTRIGHT and SHIFTLEFT retum zeroes when the number of places to shift 
is negative, or is greater than twice the transputer's word length. In this case they 
may take a long time to execute. 

ASHIFTRIGHT, ASHIFTLEFT, ROTATERIGHT and RDTATELEFT are all invalid 

when the number of places to shift is negative or exceeds the transputer's word 

length. 
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1 The Occam libraries 



1.3.3 2D block moves 

This section desoibes compiler library block move routines available to the 
programmer. 



Procedure 


Parameter Specifiers 


M0VE2D 


VAL [][]BYTE Source, 

VAL INT »x, »Yf [ItlBTfTK Dest, 

VAL INT dx, dy, widths length 


DRAH2D 


VAL [][]BYTE Source, 

VAL INT 8X, By, [] []BYTE Da«t, 

VAL INT dx, dy, width, length 


CLIP2D 


VAL [] []BYTE Source, 

VAL IKT mx, »y, [] []BYTE De»t, 

VAL IKT dx, dy, width, length 



M0VE2D 



PROC M0VE2D (VAL [] [IBYTE Source, 

VAL INT sx, sy, [] []BYTE Dest, 
VAL INT dx, dy, width, length) 

Moves a data block of size width by length starting at byte 
Source [sy] [sx] to the block starting at Dest [dy] [dx]. 

This is equivalent to: 

SEQ y = FOR length 

[De8t[y+cly] FROM dx FOR width] : = 
[Source [y+sy] FROM sx fGSL width] 

DRAH2D 

FROC DRAH2D (VAL [] []BYTE Source, 

VAL INT sx, sy, [J []BYTE Dest, 
VAL INT dx, dy, width, length) 

As M0VE2D but only non-zero bytes are transferred. 

This is equivalent to: 

SEQ line = FOR length 
SEQ point = FOR width 

VAL ten^ IS Source [line+sy] [point+sx] : 
IF 

ten^ <> (O(BYTE)) 

Dest[line+dy] [point+dx] :^ temp 
TRUE 
SKIP 
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CLIP2D 

PROC CLIP2D (VAL [] []BYTE Source, 

VAL INT sx, ay, [] [JBYTE Dest, 
VAL INT dx, dy, width, l«ngth) 

As M0VE2D but only zero bytes are transferred. 

This is equivalent to: 

SEQ line = FOR length 
SEQ point = FOR width 

VAL ten^ IS Source [line+sy] [point+sx] : 
IF 

ten?) = CO(BYTE)) 

Dest[line+dy] [point+dx] := OfBYTE) 
TRUE 
SKIP 

1.3.4 Bit manipulation functions 

Tliis section describes compiler library bit-based routines available to the 
programmer. 



Result 


Function name 


Parameter Specifiers 


INT 


BITCOONT 


VAL INT Word, Countin 


INT 


BITREVNBITS 


VAL INT X, n 


INT 


aiTREVWOKD 


VAL INT X 



BITCOUNT 

INT FUNCTION BITCOUNT (VAL INT Word^ CountIn) 

Counts the number of bits set to 1 in Word, adds it to Countin, and returns 
the total. 

BITREVNBITS 

INT FUNCTION BITREVNBITS {VAL INT X, n) 

Returns an INT containing the n least significant bits of x in reverse order. 
The upper bits are set to zero. The operation is invalid if n Is negative or 
greater tiian the number of bits in a word. 

BITREVWORD 

INT FUNCTION BITREVWORD (VAL INT x) 

Retums an int containing the bit reversal of x, 
72TDS368 01 March 1993 
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1.3.5 CRC functions 

This section describes compiler library CRC functions available to the 
programmer. 



Result 


Function name 


Parameter Specifiers 


INT 


CRCWORD 


V3tL INT data; CRCIn, 
generator 


INT 


CRCBYTE 


VAL INT data, CRCIn, 
generatior 



A cyclic redundancy check value is the remainder from modulo 2 polynomial divi- 
sion. Consider bit sequences as representing the coefficients of polynomials; for 
example, the bit sequence 10100100 (where the leading bit is the most significant 
bit) corresponds to F\x) = x^ + x® + ;^, CRCWORD and crcbyte calculate the 
remainder of the modulo 2 polynomial division: 

(x"HM+ F{x)}/G(x) 

where: F{x) corresponds to data (the whole word for CRCWORD; only the most 
significant byte for CRCBYTE) 

6(x) corresponds to generator 

H{x) corresponds to CRCin 

n is the word size in bits of the processor used (i.e. n is 16 or 32). 

(CRCIn can be viewed as the value thai would be pre-loaded into the cyclic 
shift register that is part of handware implementations of CRC generators.) 

When representing G(x) in the word generator, note that there is an understood 
bit before the msb of generator. For example, on a 16-bit processor, with G(x) 
= x''^ + x^2 + ;f5 + -j^ which is #11021, then generator must be assigned #1021 , 
because the bit corresponding to x'^^ is understood. Thus, a value of #9603 for 
generator, corresponds to G(;0 = x^^ ^ x^^ + x^^ +x^^ -^ i^ + x -^ "[.tor a ^ 6-bit 
processor. 

A similar situation holds on a 32-bit processor, so that: 

G(x) = X^ + x26 + x23+x22 + x16 + ;f12 + x^1+x10 + x8 + x7 + xS+x4 + x2 + X+1 

is encoded in generator as #04C11DB7. 

It is possible to calculate a 16-bit CRC on a 32-bit processor. For example If G(x) 
= x''^ + x"'2 + x^ + 1 , then generator is #10210000, because the most significant 
16 bits of the 32-bit integer form a 16-bit generator and for: 

CRCWORD, the least significant 16 bits of CRCIn fonn the Initial CRC value; 
the most significant 16 bits of data form the data; and the calculated CRC 
is the most significant 1 6 bits of the result. 
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12 1,3 Compiler libraries 

CRCBYTE, the most significant 1 6 bits of Otcin form the initial CRC value; 
the next 8 bits of CRCin (the third most significant byte) form the byte of 
data; and the calculated CRC is the most significant 16 bits of the result 

CRCWORD 

INT FUNCTION CRCWORD (VAL INT data, CRCIiif generator) 

Takes the whole of the word data to correspond to F(x) in the above 
formula. This implements the following algorithm: 



INT MyData, CRCOut, OldCRC : 
VMX)F 
SEQ 

MyData, CRCOut := data, CSCIn 
SEQ i = FOR BitsPorWord — 16 or 32 
SEQ 

OldCRC := CRCOut 

CRCOut, MyData := SHIFTLEFT (CRCOut, MyData, 1) 

IF 

OldCRC < — KSB of CRC = 1 

CRCOut := CRCOut X generator 
TRUE 
SKIP 
RESULT CRCOut 



CRCBYTE 

INT FUNCTION CRCBYTE (VAL INT data, CRCin, generator) 

Takes the most significant byte of data to correspond to F(x) in the above 
formula. This implements the following algorithm: 



INT MyData, CRCOut, OldCRC : 
VALOF 
SEQ 

MyData, CRCOut := data, CRCIn 
SEQ i = FOR 8 
SEQ 

OldCRC := CRCOut 

CRCOut, MyData := SHIFTLEFT (CRCOut, MyData, 1) 

IF 

OldCHC < — MSB of CRC = 1 

CRCOut := CRCOut X ganorator 
TRITE 
SKIP 
RESULT CRCOut 
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Note: The predefines CRCBYTE and CBCHORD can be chained together to help 
calculate a CRC from a string considered as one long polynomial. A simple 
chaining would calculate: 

(x'fHW+ F(x))/G(x) 

where F^ con^esponds to the string and ^ is the number of bits in the string. This 
is not the same CRC that Is calculated by crcfbohhsb and Crcfeu^mlsb in 
crc* lit), section 1.9, because these latter routines shift the numerator by xP. 



1.3.6 Floating point arithmetic support functions 



Resu»(s) 


Function name 


Parameter Specifiers 


INT 


FRACMOL 


VAL INT X, y 


INT, INT, INT 


UNPACKSN 


VAL INT X 


INT 


RDUNDSN 


VAL INT Yexp, Yfrac, Yguard 



FRAC3I0L 



INT FUNCTION FRACMUL (VAL INT z, y) 

Performs a fixed point multiplication of x and y, treating each as a binary 
fraction In the range [-1^ 1), and retuming their product rounded to the 
nearest available representation. The value of the fractions represented by 
the arguments and result can be obtained by multiplying their INT value by 
2"^^ (on a 32-bit processor) or 2*^^ (on a 1 6-btt processor). The result can 
overflow if both x and y are -1 .0. 

This routine is compiled inline into a sequence of transputerinstructions on 
32-bit processors, or as a call to a standard library routine for 1 6-bit proces- 
sors. 



DNFACKSN 



INT, INT, INT FUNCTION UNPACKSN (VAL INT x) 

This returns three parameters; from left to rightthey arexf rac, Xexp, and 
Type. X is regarded as an IEEE single length real number (i.e. a retyped 
REAL32). The function unpacks x into Xexp, the (biased) exponent, and 
Xf rac the fraction al part, with implicit b it restored . It also retums an integer 
defining the Type of x, ignoring the sign bit: 



Type 


Reason 





X is zero 


1 


X is a normalized or denonnalized number 


2 


X is Inf 


3 


XlsNaN 
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Examples: 

UNFACKSN (#40490FDB) returns #C90rDB00 ,#00000080, 1 
UKPACKSN (#00000001) returns #00000100 ,#00000001, 1 
UKPACKSH (#7FC00001) returns #40000100 ,#OOOO00FF, 3 

This routine is compiled inline into a sequence of transputer instructions on 
32-bit processors such as the IHS T425, which do not have a floating 
support unit, but do have special instructions for floating point operations. 
For other 32-bit processors the function is compiled as a call to a standard 
library routine, ft is invalid on 1 6-bit processors, since Xfrac cannot fit into 
an INT. 

ROUNDSN 

INT FUNCTION ROUNDSN (VAL INT Yexp, Yfrac, Yguard) 

This takes a possibly unnormalized fraction, guard word and exponent, and 
returns the IEEE single length floating point value it represents. It takes 
care of all the normalization, post-normalization, rounding and packing of 
the result. The rounding mode used Is round to nearest. The exponent 
should already be biased. This routine is not intended for use with Yexp 
and Yfrac representing an infinity or a NaN. 

Examples: 

ROtJNDSN (#00000080, #C90FDBOO, #00000000) returns #40490FDB 
ROUNDSN (#00000080, #C90FDB80, #00000000) returns #40490FDC 
ROUNDSN (#00000080, #C90FDA80, #00000000) returns #40490FDA 
ROUNDSN (#00000080, #C90FDA80, #00003000) returns #404 90FDB 
ROUNDSN (#00000001, #00000100, #00000000) returns #00000001 

The function normalizes and post-nomializes the number represented by 
Yexp, Yfrac and Yguard into local variables Xexp, Xfrac, and Xguard. 
It then packs the (biased) exponent X^xp and fraction Xfrac into the 
result, rounding using the extra bits in Xguard. The sign bit is set to 0. If 
overflow occurs, Inf is returned. 

This routine is compiled inline into a sequence of transputer instructions on 
32-bit processors such as the IMS T425, which do not have a floating 
support unit, but do have special instructions for floating point operations. 
For other 32-bit processors the function is compiled as a call to a standard 
library routine. It is invalid on 1 6-blt processors, since Xfrac cannot fit into 
an INT. 
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1,37 Dynamic code loading support 

This section describes ODmplIer library dynamic loading routines available to the 
programmer. 

Procedures 



Procedure 


Parameter Specifiers 


KERNEL*PDH 


VAL []BYTE code, 
VAL INT entry, off set, 
[]INT workspace r 
VAL INT no, of -parameters 


LOAD . INPUT . CHANNEL 


INT here, 

CHAN OF ANY in 


LOAD , INPUT . CHAHNEL , VECTOR 


INT here, 

(]CHAN OF ANY in 


LOAD . OUTPUT , CHANNEL 


INT here, 

CHAN OF ANY out 


LOAD . OUTPUT . CHANNEL .VECTOR 


INT here; 

[]CHAN OF ANY out 


LOAD. BYTE. VECTOR 


INT here, 

VAL I] BYTE bytes 



Functions 



Resuit(s) 


Function name 


Parameter Specifiers 


INT 


WSSIZEOF 


routinename 


INT 


VSSIZEOF 


routinename 



KERNEL. RON 



PROC KERNEL. RUN (VAL []BYTE code, 

VAL INT entry, offset, 
[]INT workspace, 
VAL INT no. of .parameters) 



The effect of this procedure is to call the procedure loaded in the code 
buffer, starting execution at the location code [entry . offset] . 

The code to be called must begin at a wond-aligned address. To ensure 
proper alignment either start the an^y at zero or realign the code on a word 
boundary before passing it into the procedure. 

The workspace buffer is used to hold the local data of the called proce- 
dure. The required size of this buffer, and the code buffer, must be derived 
by visually inspecting the executable code file (.rsc file) to be loaded 
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using the binary lister tool iliat. Alternatively, a routine can be written to 
read this file and pass the information to KERNEL. RUN. The format of the 
. rsc file is described in section 3.6 of the Tools Reference Manual, 

The parameters passed to the called procedure should be placed at the top 
of the workspace buffer by the calling procedure before the call of 
KERNEL. RUN. The Call to KERNEL. RUN retums when the called procedure 
terminates. If the called procedure requires a separate vector space, then 
another buffer of the required size must be declared, and its address 
placed as the last parameter at the top of workspace. As calls of 
KERNEL. RUN are handled specially by the compiler it is necessary for 
no , of , parameters to be a constant known at compile time and to have 
a value > 3. 

The workspace passed to kernel -RUN must be at least: 

[ws. requirement + (no . of . parameters + 2)]INT 

where ws . requirement is the size of workspace required, determined 
when the called procedure was compiled and stored in the code file, and 
no , of . parameters includes the vector space pointer if it is required. 

The parameters must be loaded before the call of KERNEL. RUN. The 
parameter corresponding to the first formal parameter of the procedure 
should be in the word adjacent to the saved Iptr word, and the vector space 
pointer or the last parameter should be adjacent to the top of workspace 
where the Wptr word wll be saved. 

LOAD . INPUT . CHANNEL 

LOAD. INPUT. CHANNEL (INT here, CHAN OF ANY in) 

The variable here is assigned the address of the input channel in. 

The normal protocol checking of channel parameters is suppressed; there- 
fore channels of any protocol may be passed to this routine. The channel 
parameter is considered by the compiler to have been used for input. 

LOAD . INPUT . CHANNEL . VECTOR 

LOAD. INPUT. CHANNEL. VECTOR (INT here, 

[]CHAN OF ANY in) 

The variable here is assigned the address of the base element of the 
channel array in (i.e. the base of the array of pointers). 

The nomial protocol checking of channel parameters is suppressed; there- 
fore channels of any protocol may be passed to this routine. The channel 
parameter is considered by the compiler to have been used for input. 
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LOAD . OUTPUT . CHANHEL 

LOAD. OUTPUT. CHANNEL {INT here^ CHAN OF ANY out) 

The variable here is assigned the address of the output channel out. 

The normal protocol checldng of channel parameters is suppressed; there- 
fore channels of any protocol may be passed to this routine. The channei 
parameter Is considered by the compiler to have been used for input. 

LOAD . OUTPUT . CHANNEL . VECTOR 

LOAD. OUTPUT. CHANNEL. VECTOR (INT here, 

[]CHAN OF ANY out) 

The variable here is assigned the address of the base element of the 
channei array out (i.e. the base of the array of pointers). 

The normal protocol checking of channel parameters is suppressed; there- 
fore channels of any protocol may be passed to this routine. The channel 
parameter is considered by the compiler to have been used for input. 

LOAD. BYTE. VECTOR 

LOAD. BYTE. VECTOR (INT here, VAL []BYTE bytes) 

The variable here is assigned the address of the byte array bytes. This 
can be used in conjunction with retypes to find the address of any vari- 
able. 

WSSIZEOF 

INT FUNCTION WSSIZEOF (routinenaM) 

This ftjnction returns the number of workspace 'slots' (words) required by 
the procedure or function routinename. INLINE or predefined routines are 
not permitted. 

VSSIZEOF 

INT FUNCTION VSSIZEOF (routinename) 

This function returns the number of veclorspace 'slots' (worcls) required by 
the procedure or function routinename. INLINE or predefined routines 
are not permitted. 

1.3.8 Transputer-related procedures 

This section describes compiler library transputer-specific routines available to the 
programmer. 
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Procedure 


Parameter Specifiers 


CAUSEERROR 





RESCHEDULE 






CAUSEERROR 

CAUSEERROR C) 

Inserts instructions into the program to set tine transputer error flag. If tlie 
program is in STOP or UNIVERSAL mode instructions to stop the current 
process are also inserted. 

The error is then treated in exactly the same way as any other error would 
be treated In the error mode in which the program is compiled. For 
example, in HALT mode the whole processor will halt and in STOP mode 
that process will stop, leaving the transputer error flag set true. If run-time 
error checking has been suppressed (e.g. by a command line option)» this 
stop is suppressed. 

The difference between CAUSEERROR () and the STOP process, is that 
CAUSEERROR guarantees to set the transputer's en'or flag. 

RESCHEDULE 

RESCHEDULE 

This causes the current process to be rescheduled by inserting instructions 
into the program to cause the current process to be moved to the end of 
the current priority scheduling queue. This occurs even if the current 
process is a 'high prionty' process. 

RESCHEDULE effectively forces a 'timeslice', even in high priority. 



1.3.9 Miscellaneous operations 

This section describes miscellaneous compiler library routines available to the 
programmer. 



Procedure 


Parameter Specifiers 


ASSERT 


"^TKL BOOL test 



ASSERT 

PROC ASSERT (VAL BOOL test} 

At compile time the compiler will check the value of test and if it is false 
the compiler will give a compile time error; if it is TRUE, the compiler does 
nothing. If test cannot be checked at compile-time then the compiler will 
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insert a run-Ome check to detect its status. This run-time check may be 
disabled by means of a command line option. 

ASSERT is a useful routine for debugging purposes. Once a program is 
working con-ectly the compiler option "NA* can be used to prevent code 
being generated to check for ASSERTS at run-time. If possible asserts will 
still be checked at compile time. 
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1.4 Maths libraries 

Elementary maths and trigonometric Unctions are provided in three libraries, as 
follows: 



Library 


Description 


snglmath . lib 


Single length library 


dblmath,lib 


Double length library 


tbmaths . lib 


IB optimized library 



The single and double length libraries cx)ntain the same set of maths functions in 
single and double length forms. The double length forms all begin with the letter 
'D'. All function names are in upper case. 

The TB optimized library is a combined single and double length library containing 
functions forthe T4 series (T400, T414, T425, and T426). The functions have been 
optimized for speed. The standard single or double length libraries can be used on 
T4 processors but optimum performance will be achieved by using the TB opti- 
mized library. The accuracy of the T400/T414rr425/T426 optimized functions is 
similar to that of the standard single length functions but results returned may not 
be identical because different algorithms are used. If the optimized library is used 
in code compiled for any processor except a T400, T414, T425, or T426, the 
compiler reports an error 

To obtain the best possible speed perfomnance wtth the Occam maths lijnctions 
use the following strategy: 

» For networks consisting of only T4 series transputers, use the 
tbmaths . lib library. 

• For networks consisting of only T8 series transputers, use the 
snglmath. lib and dblmath.lib libraries. 

• For networks consisting of a mix of T4 series and T8 series transputers use: 

tbmaths. lib On the T4 series and snglmath. lib or 
dblmath. lib on the T8 series When a consistent level of accu- 
racy is not required; 

o if accuracy must be the same in the T8 and T4 processes then use 
the snglmath . lib and dblmath , lib libraries. 

Constants for the maths libraries are provided in the include file matkvals . inc. 

The elementary function library is also described in appendix N of the occam 2 
Reference manual. 

1.4.1 Introduction and terminology 

This, and the following subsections, contain some notes on the presentation of the 
elementary function libraries described in section 1.4.2, and the TB version 
described in section 1 .4.3. 
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These function subroutines have been written to be compatible with the ANSI stan- 
dard for binary floating-point arithmetic {ANSI-IEEE std 754-1985), as imple- 
mented in Occam. They are based on the algorithms in: 

Cody, W- J., and Walte, W. M. [1980]. Software Manual for the Elementary 
FurK^ions. Prentice-Mall, New Jersey. 

The only exceptions are the pseudo-random number generators, which are based 
on algorithms in: 

Knuth, D. E, [1981], The Art of Computer Programming, 2nd. edition, 
Volume 2: Seminumericai Atgontbms. Addison-Wesley, Reading, Mass. 

Inputs 

All the functions in the library (except rah and dran) are called with one or two 
parameters which are binary floating-point numbers in one of the IEEE standard 
formats, either 'single-length' (32 bits) or 'double-length' (64 bits). The param- 
eter(s) and the function result are of the same type, 

NaNs and Infs 

The functions will accept any value, as specified by the standard, including special 
values representing NaNs ('Not a Number') and Infs ('Infinity'). NaNs are copied 
to the result, whilst infs may or may not be in the domain. The domain is the set 
of arguments for which the result is a normal (or denormalized) floating-point 
number. 

Outputs 

Exceptions 

Arguments outside the domain (apart fi^om NaNs which are slxrvpAy copied through) 
give rise to exceptional results, which may be NaN, +lnf, or -Inf. Infs mean that 
the result is mathematically well-defined but too large to be represented in the float- 
ing-point formaL 

Error conditions are reported by means of three distinct NaNs: 

undefined.NaN 

This means that the function is mathematically undefined for this argument, for 
example the logarithm of a negative number. 

unstable.NaN 

This means that a small change in the argument would cause a large change in 
the value of the function, so any error in the input will render the output meaning- 
less. 

InexactKaN 

This means that although the mathematical function is well-defined, its value is In 
range, and It Is stable with respect to input en-ors at this argument, the limitations 
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of word-length (and reasonable cost of the algorithm) make It impossible to 
compute the correct value. 

The implementations will return the following values for these Not-a-Numbers: 



Error 


Single length value 


Double length value 


undefined. NaM 


#7F800010 


#7FF00002 00000000 


uns table. NoN 


#7F800008 


#7FF00001 00000000 


inexact, NaN 


#7F800004 


#7FFOOOO0 80000000 



Accuracy 

Range Reduction 

Since it is impradical to use rational approximations (i.e. quotients of polynomials) 
which are accurate over large domains, nearly all the subroutines use mathemat- 
ical identities to relate the function value to one computed from a smaller argument, 
talcen from the 'primary domain', which is small enough for such an approximation 
to be used. This process is called 'range reduction' and is perfomied for all argu- 
ments except those which already lie in the primary domain. 

For most of the functions the quoted error is for arguments in the primary domain, 
which represents the basic accuracy of the approximation. For some functions the 
process of range reduction results in a higher accuracy for arguments outside the 
primary domain, and for others it does the reverse. Refer to the notes on each fijnc- 
tion for more details. 

Generated Error 

If the true value of the function is large the difference between it and the computed 
value (the 'absolute error') Is likely to be large also because of the limited accuracy 
of floating-point numbers. Conversely if the true value is small, even a small abso- 
lute en"or represents a large proportional change. For this reason the error relative 
to the true value is usually a better measure of the accuracy of a floating-point func- 
tion, except when the output range is strictly bounded. 

If /Is the mathematical function and J^ the subroutine approximation, then the rela- 
tive error at the floating-point number A* (provided /(^ is not zero) is: 



m^ 






Obviously the relative en'or may become very large near a zero of/t?). If the zero 
is at an in^ational argument (which cannot be represented as a floating-point value), 
the absolute error is a better measure of the accuracy of the function near the zero. 

As it is Impractical to find the relative error for every possible argument, statistical 
measures of the overall error must be used. If the relative enor Is sampled at a 
number of points -S^ (» = 1 to N), then useful statistics are the maximum relative 
error and the root-mean-square relative error. 
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MRE~ max \RE(JOt)\- 



RMSRE 



Jj^im^n)? 



Corresponding statistics can be formed for the absolute en-oralso, and are called 
MAE and RMSAE respectively. 

The MRE generally occurs near a zero of the function, especially if the true zero 
is irrational, or near a singularity where the result is large, since the 'granularity' of 
the floating-point numbers then becomes significant. 

A useful unit of relative error is the relative magnitude of the least significant bit in 
the floating-point fraction, which is called one 'unit in the last place" (ulp), (i.e. the 
smallest e such that 1+e ?* 1). Its magnitude depends on the floating-point format: 
for single-length it is 2-23= 1 .19*1Cr^ and for double-length it is 2-52 = 2.22*1Cr^6. 

Propagated Error 

Because of the limited accuracy of floating-point numbers the result of any calcula- 
tion usually differs from the exact value. In effect, a small en-or has been added to 
the exact result^ and any subsequent calculations will inevitably involve this error 
temi. Thus it is important to determine how each function responds to en-ors in its 
argument Provided the en-or is not too large, It is sufficient just to consider the first 
derivative of the function (written/'). 

If the relative en-or in the argument X\&d (typically a few ulp), then the absolute 
error (£) and relative error (e) in/(X) are: 

£= \Xf{X)d\~ Ad 
Xr(X)d 



/W 



= Rd 



This defines the absolute and relative enw magnification factors^ and R. When 
both are large the function is unstable, i.e. even a small en-or in the argument, such 
as would be produced by evaluating a floating-point expression, will cause a large 
en*or in the value of the ftjnction. The functions return an unslable.NaN in such 
cases v^ich are simple to detect. 

The functional forms of both^ and R are given in the spedtication of each ftjnction. 
Test Procedures 

For each function, the generated en^or was checked at a large number of argu- 
ments (typically 100 000) drawn at random from the appropriate domain. First the 
double-length functions were tested against a 'quadruple-length' implementation 
(constructed for accuracy rather than speed), and then the single-length functions 
were tested against the double-length versions, 
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In both cases the higher-precision implementation was used to approximate the 
mathematical function (called/above) in the computation of the en-or, which was 
evaluated in the higher precision to avoid rounding errors. Error statistics were 
produced according to the fomiulae above. 

Symmetry 

The subroutines were designed to reflect the mathematical properties of the func- 
tions as much as possible. For all the functions which are even, the sign is removed 
from the input at the beginning of the computation so that the sign-symmetry of the 
function is always preserved. For odd functions, either the sign Is removed at the 
start and then ^e appropriate sign set at the end of the computation, or else the 
sign is simply propagated through an odd degree polynomial. In many cases other 
symmetries are used in the range-reductioni with the result that they will be satis- 
fied automatically. 

The Function Specifications 

Names and Parameters 

All single length functions except ran retum a single result of type EEaL32, and 
all except ran, power and ATAN2 have one parameter, a val REAL32. 

POWER and ATAN2 have two parameters which are val R£AL32s for the two argu- 
ments of each function. 

RAN retums two results, of types B£AL32 and INT32, and has one parameter 
whichisaVALlNT32. 

In each case the double-length version of name is called Dname, retums a REAL64 
(except DRAH, which returns REAL64, INT64), and has parameters of type 
VAL REAL64 (VAL INT64 for DRAN). 

Terms used In the Specifications 

A and R Multiplying factors relating the absolute and relative em:»rs in the output 
to the relative en'or in the argument. 

Exceptions Outputs for invalid inputs (i.e. those outside the domain), other than 
NaN (NaNs are copied directly to the output and are not listed as exceptions). 
These are all Infs or NaNs. 

Generated Error The difference between the true and computed values of the 
function, when the argument is error-free. This is measured statistically and 
displayed for one or two ranges of arguments, the first of which is usually the 
primary domain (see below). The second range, if present, is chosen to illus- 
trate the typical behavior of the function. 

Domain The range of valid inputs, i.e. those for which the output is a normal or 
denormal floating-point number. 

MAE and RMSAE The Maximum Absolute En'or and Root-Mean-Square absolute 
error taken over a number of arguments drawn at random from the indicated 
range. 
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MRE and RMSRE The Maximum Relative Error and Root-Mean-Square relative 

error taken over a number of arguments drawn at random from the indicated 

range. 
Range The range of outputs produced by all arguments in the Domain. The given 

endpoints are not exceeded. 
Primary Domain The range of arguments for which the result is computed using 

only a single rational approximation to the function. There is no argument 

reduction in this range. 
Propagated Error The absolute and relative error in the function value, given a 

small relative error in the argument. 
ulp The unit of relative en-or is the 'unit in the last place' (ulp). This is the relative 

magnitude of the least significant bit of the floating-point fraction (i.e. the 

smallest £ such that 1+e ^ 1). 

N.B. this depends on the Hoating-point format. 

For the standard single-length format it is 2r^^ = 1.19*10"^. 

For the double-length format it is 2r^^ = 2.22*10-''^. 

This is also used as a measure of absolute error, since such errors can be 

considered 'relative' to unity. 

Specification of Ranges 

Ranges are given as intervals, using the convention that a square bracket T or T 
means that the adjacent endpoint is included in the range, whilst a round bracket 
'(' or ')' means that it is excluded. Endpoints are given to a few significant figures 
only. 

Where the range depends on the floating-point fomiat, single-length is indicated 
with an S and double-length with a D. 

For functions with two arguments the complete range of both arguments is given. 
This means that for each numberin one range, there is at least one (though some- 
times only one) number in the other range such that the pair of arguments is valid. 
Both ranges are shown, linked by an 'x'. 

Abbreviations 

In the specifications, J?M^J¥' is the largest representable floating-point number: in 
single-length it is approximately 3,4*10^, and in double-length it is approximately 
1.8*10308 

Pi means the closest floating-point representation of the transcendental number 
K, ln(2) the closest representation of logi(2), and so on. 

In describing the algorithms, *X is used generically to designate the argument, and 
'result' (or RESULT, in the style of Occam functions) to designate the output 

^A2 Single and double length elementary function libraries 

The versions of the libraries described by this section have been written using only 
floating-point arithmetic and pre-defined functions supported in occam. Thus they 
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can be compiied for any processor with a full implementation of occam, and give 
Identical results. 

These two libraries will be efficient on processors with fast floating-point arithmetic 
and good support for the floating-point predefined Unctions such as MULBY2 and 
ARGUMENT . REDUCE. For 32-bit processors without special hardware for floating- 
point calculations the alternative optimized library described in section 1 .4.3 using 
fixed-point arithmetic will be faster, but will not give identical results. 

A special version has been produced for 1 6-bit transputers, which avoids the use 
of any double-precision arithmetic in the single precision functions. This is distin- 
guished In the notes by the annotation T2 special'; notes relating to the version for 
T8 and TB are denoted by 'standard'. 

Single and double length maths functions are listed below. Descriptions of thefunc- 
tions can be found in succeeding sections. 

To use the single length library a program header must include the line 

#USE "snglmath.lib" 
To use the double length library a program header must Include the line 

#DSE "dblmath.lib" 



Result(s) 


Function 


Paranraeter specifiers 


REAL32 


AIOG 


VAL tt£&L32 X 


REAL32 


ALOGIO 


VAL REAL32 X 


REAL32 


EXP 


VAL REAL32 X 


HEAL32 


POWER 


VAL REAL32 X, VAL REAL32 Y 


REAL32 


SIN 


VAL REAL32 X 


REAL32 


COS 


VAL REAL32 X 


REAL32 


TAN 


VAL REAL32 X 


REAL32 


AS IN 


VAL REAL32 X 


REAL32 


ACQS 


VAL REAL32 X 


REAL32 


ATAN 


VAL REAL32 X 


REAL32 


ATAN2 


VAL REAL32 X, VAL REAL32 Y 


REAL32 


SINH 


VAL BEAL32 X 


REAL32 


COSH 


VAL REAL32 X 


REAL32 


TANH 


VAL BEAL32 X 


REAL32 , INT32 


RAN 


VAL INT32 X 


REAL64 


DALOG 


VAL REAL64 X 


REAL64 


DALOGIO 


VAL REALe4 X 


REAL64 


DEXP 


VAL K£AL64 X 
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Result(5) 


Function 


Parameter specifiers 


REAL64 


DPOWER 


VAL REAL64 X, YAL REAL64 Y 


PEAL64 


DSIN 


VAL KEJ^64 X 


REAL64 


DCOS 


VAL REAL64 X 


REAL64 


DTAN 


VAL REAL64 X 


REAL64 


DAS IN 


VAL REAL64 X 


REAL64 


DACOS 


VAL REALe4 X 


»£AL64 


DATAN 


VAL REAL64 X 


REAL64 


DATAN2 


VAL REAL64 X, VAL REAL64 Y 


R£AL64 


DSINH 


VAL REAL64 X 


REAL64 


DCOSH 


VAL REAL64 X 


IIEAL64 


DTANH 


VAL REAL64 X 


REAL64 , INT64 


DBAN 


VAL INT64 X 



Function definitions 



ALOG 
DALOG 



BEAL32 FUNCTION ALOG (VAL REAL32 X) 
REAL64 FDNCTION DALOG (VAL REAL64 X) 



W^nLog, MaxLog] [MinLog, MaxLog] (See note 2) 
V2/2, y2) = [0.7071, 1.4142) 



Compute loge(fl. 

Domain: 
Range: 
Primaty Domain: 

Exceptions 

All arguments outside the domain generate an undefined.NaN, 
Propagated Error 
A = ^, R =1/loge(30 
Generated Error 



Primary Domain En-or 


MRE 


RMSRE 


Single Lengtli(Standard): 


1.7 ulp 


0.43 ulp 


Single Length(T2 special): 


1.6 ulp 


0.42 ulp 


Double Length: 


1.4 ulp 


0,38 ulp 



The Aigorithm 

1 SplitX into its exponent JV and fraction F. 



72TDS368 01 



March 1993 



28 1.4 Maths libraries 

2 F'md LnF, the natural log olF, vwth a floating-point rational approxima- 
tion. 

3 Compute ln(2) * iV with extended precision and add it to LnF to get 
the result. 

Notes 

1) The temi ln(2) *^is much easier to compute (and more accurate) than 
LnF, and it is larger provided N is not (I.e. for arguments outside the 
primary domain). Thus the accuracy of the result improves as the modulus 
of log(jQ increases. 

2) The minimum value that can be produced, MinLog, is the logarithm of 
the smallest denormalized fioating-point number For single length MinLog 
is -1 03.28, and for double length it is -744.4. The maximum value MaxLog 
is the logarithm otXMAX. For single-length it is 88.72, and for double- 
length it is 709.78. 

3) Since Inf is used to represent a// values greater than JSMSTits logarithm 
cannot be defined. 

4) This function is well-behaved and does not seriously magnify en-ors in 
the argument. 

ALOGIO 
DALOGIO 

REAL32 FC7NCTI0N ALOGIO (VAL R£AL32 3C) 
KE:AL64 function DALOGIO (VAL HEAL64 X) 

Compute log-] o(^. 

Domain: {^,XMAX\ 

Range: [A/inL10, AfeLIO] (See note 2) 

Primary Domain: [^2/2, ^2} = [0.7071, 1.4142) 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 

Propagated Error 

A = logio(e), R - logio{e)/loge(^ 

Generated Error 

Primary Domain Error MRE RMSRE 

Single Length (Standard): 1.70 ulp 0.45 ulp 
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Single Length (T2 special): 1 .71 ulp 0.46 ulp 
Double Length: 1.84 ulp 0.45 ulp 

The Algorithm 

1 Set te/np:=ALOG(X). 

2 \itemp is a NaN, copy it to the output, otherwise set 
result =: \0Q(€)*s&np 

Notes 

1) See note 1 for ALOG. 

2) The minimum value that can be produced, MinLI 0, is the base-1 loga- 
rithm of the smallest denomialized floating-point number. For single length 
MinL^O is ^44.85, and for double length it is -323.3. The maximum value 
MwcLIO is the base-10 logarithm ofXMAX. For single length MaxL'iO is 
38.53, and for double-length it is 308,26. 

3) Since Inf is used to represent a// values greaterthan JGVf^lYits logarithm 
cannot be defined, 

4) This function is well-behaved and does not seriously magnify en-ore in 
the argument. 



DEXP 

B£AL32 FUNCTION EXP (VAL REAL32 X) 
REAI.64 FUNCTION DEXP (VAL REAL64 X) 

Computet^. 

Domain: [-Inf, MaxLog) = Hnf. 88.72)S, [-Inf, 709.78)D 

Range: [0, Inf) (See note 4) 

Primary Domain: [-Ln2J2, Ln2J2) = [-0.3466, 0.3466) 

Exceptions 

All arguments outside the domain generate an Inf. 

Propagated error 

A^Xe^, R'X 

Generated error 

Primary Domain Enor MRE RMSRE 

Single Length(Standard): 0.99 ulp 0.25 ulp 
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Single Length(T2 special): 1.0 ulp 0.25 ulp 
Double Length: 1.4 ulp 0.25 ulp 

The Algorithm 

1 Set iV = integer part of Jein(2). 

2 Compute the remainder ofZby ln(2), using extended precision arith- 
metic. 

3 Compute the exponential of the remainder with a floating-point 
rational approximation. 

4 Increase the exponent of the result by N. \fN is siifRciently negative 
the result must be denormalized. 

Notes 

1) MaxLog is \ogei,?^MAX). 

2) For sufficiently negative arguments (below -87.34 for single-length and 
below -708.4 for double-length) the output is denormalized, and so the 
floating-point number contains progressively fewer significant digits, which 
degrades the accuracy. In such cases the en'or can theoretically be a factor 
of two. 

3) Although the true exponential function is never zero, for large negative 
arguments the true result becomes too small to be represented as a float- 
ing-point number, and EXP underflows to zero. This occurs for arguments 
below -1 03.9 for single-length, and below -745.2 for double-length. 

4) The propagated error is considerably magnified for large positive argu- 
ments, but diminished for large negative arguments. 

POWER 
DPOWER 

REAL32 FUNCTION POWER (VAL REaL32 X, Y) 
REAL64 FUNCTION DPOWER {VAL REAL64 X, Y} 

Compute JT^ 

Domain: [0, Inf] x [-Inf, Inf] 

Range: (-Inf, Inf) 

Primary Domain: See note 3. 

Exceptions 

If the first argument is outside its domain, undefined.NaN is returned- If the 
true value of X^exceeds.SM4^, Inf is returned. In certain other cases other 
NaNs are produced: See note 2. 
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Propagated Error 

A = YX^il ± \og,{Xi), it = Y(1 ± logeW) {See note 4) 
Generated error 

Example Range Error MRE RMSRE (See note 3) 

Single Length(Standard): 10 ulp 0.25 ulp 

Single Length(T2 special): 63.1 ulp 13,9 ulp 

Double Length: 21.1 ulp 2.4 ulp 

The Algorithm 

Deal with special cases: either argument =1,0, -i-Inf or -Inf (see note 2}. 
Otherwise: 

(a) For the standard single precision: 

1 Compute L = log^t^ in double precision, where X is the first argu- 
ment. 

2 Compute W=YxL\n double precision, where Vis the second argu- 
ment. 

3 Compute RESULT = c^'m single precision. 

(b) For double precision, and the single precision special version: 

1 Compute L = log2(^ In extended precision, where A* is the first argu- 
ment. 

2 Compute W^YxLm extended precision, where / is the second 
argument. 

3 Compute RESULT = 2^in extended precision. 

Notes 

1) This subroutine implements the mathematical function xyto a much 
greater accuracy than can be attained using the alog and EXP functionSi 
by performing each step in higher precision. The single-precision version 
is more efficient than using dalog and EXP because redundant tests are 
omitted. 
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2) Results for special 


cases are as follows: 






First Input (X) 


Second Input (Y) 


Result 




<0 


ANY 


undefined.NaN 







^0 


undefined. NaN 







<y^XMAX 










Inf 


unstable.NaN 




<:^<1 


Inf 







<x<^ 


-Inf 


Inf 




1 


-XMAXi^Y^XMAX 


1 




1 


± Inf 


unstable.NaN 




1 <X^XMAX 


Inf 


Inf 




1 <X^XMAX 


-Inf 







Inf 


1 £ Y^ Inf 


Inf 




Inf 


-Inf sy ^ -1 







Inf 


-1 <y<i 


undefined.NaN 




othenwse 





1 




othenvise 


1 


X 



SIN 
DSIN 



3) Performing all the calculations fn extended precision nnakes the double- 
precision algorithm very conrplex in detail, and having two arguments 
makes a primary domain difficult to specify. As an indication of accuracy, 
the functions were evaluated at 100 000 points logarithmically distributed 
over (0.1, 10.0), with the exponent linearly distributed over (-35,0, 35.0) 
(single-length), and (-300.0, 300.0) (double-length), producing the errors 
given a bove. The errors are much smaller if the exponent range is reduced . 

4) The error amplification factors are calculated on the assumption that the 
relative error in y is ± that \nX, otherwise there would be separate factors 
for both X and Y It can be seen that the propagated en-or will be greatly 
amplified whenever Iogg(Z) or y is large. 



REAL32 FCINCTIOH SIN (VAL BEAL32 X) 
REAL64 FUNCTION DSIN (VAL BEAL64 X] 

Compute sineCfl (where X is In radians). 



Domain: [-Smax, Smax] 

Range: 
Primary Domain: 



= [-205887.4, 205887.4]S (Standard), 
= H.2*10^ 4.2*1 0*]S (T2 special) 
= H.29*10*, 4.29*1 O^D 

[-10,1.0] 

[-PJ/2,/^2]= [-1.57, 1.57] 
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Exceptionft 

AH arguments outside the domain generate an inexactNaN, except ± Inf, 
which generates an undefined. NaN. 

Propagated Error 

A=Xcos{X), R=Xco{{X) 

Generated error (See note 1} 

Primary Domain [0, 2Pi\ 

MRE RMSRE MAE RMSAE 

Single Length(Standard): 0,94 ulp 0.23 ulp 0.96 ulp 0.19 ulp 

Single Longth(T2 special): 0.92 ulp 0.23 ulp 0.94 ulp 0.19 ulp 

Double Length: 0.90 ulp 0.22 ulp 0.91 ulp 0.18 ulp 

The Algorithm 

1 Set JV = integer part of |^| /Pi. 

2 Compute the remainder of \X\ by ft', using extended precision arith- 
metic (double precision in the standard version). 

3 Compute the sine of the remainder using a floating-point polynomial. 

4 Adjust the sign of the result according to the sign of the argument and 
the evenness oIN. 

Notes 

1) For arguments outside the primary domain the accuracy of the result 
depends crucially on step 2. The extra precision of step 2 is lost if N 
becomes loo large, and the cut-off 5m&t is chosen to prevent this. In any 
case for large arguments the 'granularity' of floating-point numbers 
becomes a significant factor. For arguments larger than Smax a change in 
the argument of 1 ulp would change more than half of the significant bits 
of the result, and so the result Is considered to be essentially indeterminate. 

2) The propagated error has a complex behavior. The propagated relative 
en-or becomes large near each zero of the function (outside the primary 
range), but the propagated absolute eror only becomes large for large 
arguments. In effect, the en-or is seriously amplified only in an interval about 
each irrational zero, and the wdth of this interval increases roughly in 
proportion to the size of the argument. 

3) Since only the remainder of .Y by ft" is used in step 3, the symmetry 
jznCrH nx) = ±sin{K) is preserved, although there is a complication due to 
differing precision representations of k. 
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4) The output range Is not exceeded. Thus the output of sin is always a 
valid argument for ASIH. 

cos 

DCOS 

REAL32 FONCTION COS (VAL REAL32 X) 
EEAL64 FUNCTION DCOS (VRL REAL64 X) 

Compute cosine(^ (whereXIs in radians). 

Domain: [-Cmax, Cmax] - [-205887.4, 205887.4]S (Standard), 
= [-12868.0, 12868.0]S (T2 special) 
= [-2.1*10S,2.1*10^D 

Range: [-1.0, 1.0] 

Primary Domain: See note 1. 

Exceptions 

All arguments outside the domain generate an Inexact.NaN, except dilnf, 
which generates an undeHned.NaN. 



Propagated Error 




A = -Xsin (jf), R = 


-Xtani^ (See note 4) 


Generated error 






10, Pi/4] [0,2/^1 




MRE RMSRE MAE RMSAE 



Single Length(Standard): 0.93 ulp 0.25 ulp 0.88 ulp 0.18 ulp 
Single Length(T2 special): 1.1 ulp 0.3 ulp 0.94 ulp 0.19 ulp 
Double Length: 1.0 ulp 0.28 ulp 0.90 ulp 0.19 ulp 

The Algorithm 

1 Set^=integerpartof(|X| +i^72)/jRf and compute the remainder of 
{ |Z| +Pi/2) by Pi, using extended precision arithmetic (double preci- 
sion in the standard version). 

2 Compute the sine of the remainder using a floating-point polynomial. 

3 Adjust the sign of the resuft according to the evenness ofN. 

Notes 

1) Inspection of the algorithm shows that argument reduction always 
occurs, thus there is no 'primary domain' for COS. So for all arguments the 
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accuracy of the result depends crucially on step 2. The standard single-pre- 
cision version perfomis the argument reduction in double-precision, so 
there is effectively no loss of accuracy at this step. For the T2 special 
version and the double-precision version there are effectively K extra bits 
in the representation of tc(JC=S for the former and 12 for the latter). If the 
argument agrees with an odd integer multiple of n/2 to more than h bits 
there is a loss of significant bits from the computed remainder equal to the 
number of extra bits of agreement, and this causes a loss of accuracy in 
the result. 

2) The difference between COS evaluated at successive floating-point 
numbers is given approximately by the absolute eror amplification factor, 
A. For arguments larger than Cmaxttxis difference may be more than half 
the significant bits of the result, and so the result is considered to be essen- 
tially indeterminate and an inexact.NaN is returned. The extra precision of 
step 2 in the double-precision and T2 special versions is lost if iV becomes 
too large, and the cut-off at Cmax prevents this also. 

3) For small arguments the errors are not evenly distributed. As the argu- 
ment becomes smaller there is an increasing bias towards negative errors 
(which is to be expected from the form of the Taylor series). For the single- 
length version and Jfin [-0.1, 0.1], 62% of the en^ors are negative, whilst 
forJTin [-0.01, 0.01], 70% of them are. 

4) The propagated error has a complex behavior. The propagated relative 
en-or becomes large near each zero of the funcfon, but the propagated 
absolute error only becomes large for large arguments. In effect, the error 
IS seriously amplified only in an interval about each irrational zero, and the 
width of this interval increases roughly in proportion to the size of the argu- 
ment. 

5) Since only the remainder of (\X\*Pi!2) by Pi is used in step 3, the 
symmetry cos(rfr roi ) = ± costt) is preserved. Moreover, since the same 
rational approximation is used as in SIN, the relation cosM = sintr+n/2) is 
also preserved. However, in each case there is a complication due to the 
different precision representations of it. 

6) The output range is not exceeded. Thus the output of cos is always a 
valid argument for ACQS. 

TAN 

DTAN 

it£AL32 FUNCTION TAN (VAL BEAL32 X) 
REAL64 FUNCTION DTAN (VAL REAL64 X} 

Compute tan(;C) (where Jf is in radians). 
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Domain: [-Tmax, Tmax] = [-102943.7, 1 02943.7IS(Standard), 
= [-2.1*10«, 2,1*10fi]S(T2 special), 
= [-2.1*10^2.1*10^0 

Range: (-Inf, Inf) 

Primary Domain: [-Pi/A, PifA]= [-0.785, 0.785] 

Exceptions 

AH arguments outside the domain generate an inexact.NaN, except dr Inf , 
which generate an undefined.NaN. Odd integer multiples of ji/2 may 
produce unstabJe.NaN. 

Propagated Error 

A=X{^+ tan2(^), R-X{-\+ tan^ (;X))/\an(^ (See note 3) 

Generated error 

Primary Domain En-or MRE RMSRE (See note 3) 

Single Length(Standard): 1.44 u!p 0.39 ulp 

Singie Lengfh(T2 speciai): 1.37 ulp 0.39 ulp 

Double Length: 1.27 ulp 0.35 ulp 

The Aigorithm 

1 Se\N= integer part of X/(Pif/2), and compute the remainder of Z by 
Pit2, using extended precision arithmetic. 

2 Compute two floating-point rational functions of the remainder, 
XNum and XDen. 

3 If iV is odd, set RESULT = - XDmlXNum, othenflrise set RESULT = 
XNumlXDm, 

Notes 

1) ii is large whenever A" is near to an integer multiple of jt/2, and so tan 
is very sensitive to small en-ors near its zeros and singularities. Thus for 
arguments outside the primary domain the accuracy of the result depends 
cmcially on step 2, so this is performed with very high precision, using 
double precision Pil2 for the standard single-precision function and two 
double-precision floating-point numbers for the representation of jc/2 for 
the double-precision function. The T2 special version uses two single-pre- 
cision floating-point numbers. The extra precision is lost if ^becomes too 
large, and the cut-off Tmax is chosen to prevent this. 

2) The difference between TW« evaluated at successive floating-point 
numbers is given approximately by the absolute en-or amplification factor, 
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A. For arguments larger than Smax this difference could be more than half 
the significant bits of the result, and so the result is considered to be essen- 
tially indeterminate and an InexaciNaN is returned. 

3) Tan is quite badly behaved with respect to errors in the argument. Near 
its zeros outside the primary domain the relative eiTor is greatly magnified, 
though the absolute enor is only proportional to the size of the argument. 
In effect, the en-or is seriously amplified in an interval about each in-ationai 
zero, whose width increases roughly in prciportion to the size of the argu- 
ment Near its singularities both absolute and relative errors become large, 
so any large output from this function is liable to be seriously contaminated 
with error, and the larger the argument, the smaller the maximum output 
which can be trusted. If step 3 of the algorithm requires division by zero, 
an unstable.NaN is produced instead. 

4) Since only the remainder ofXbyPil2 is used in step 3, the symmetry 
tantc+ wt ) = tantc) is preserved, although there is a complication due to the 
differing precision representations of jt. Moreover, by step 3 the symmetry 
tan(r) = 1/tan( tcI2 -x) is also preserved. 



A5IN 
DASIN 

BEAL32 FUNCTION 
REAL64 FUNCTION 

Compute sine"^C^ 


ASIN (VAL R£J^32 X) 
DASIN (VAL REAL64 X) 

(in radians). 










Domain: 
Range: 
Primary Domain: 


[-1.0. 1.0] 
l-Pi/2,Pi/2] 
[-0.5. 0.5] 










Exceptions 

All arguments outside the domain generate an undefined.NaN. 

Propagated Error 

A =J¥'/yi -Jfi, R=XI{s\n-^m yi -^ 
Generated Error 








Primary Domain 
MRE RMSRE 


[-1.0 
MAE 


.10] 
RMSAE 




Single Length: 
Double Length: 


0.58 ulp 0.21 ulp 
0.59 ulp 0.21 ulp 


1.35 ulp 
1.26 ulp 


0.33 
0.27 


ulp 
ulp 



The Algorithm 

1 If W > 0.5, seiXwork- SQRT((1 - |-Sr|)/2}, Compute RwoHc = 
arcsine(-2 *Xwork) with a floating-point rational approximation, and 
set the result = Rwork + Pill. 
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2 Otherwise compute the result directly using the rational approxima- 
tion. 

3 In either case set the sign of the result according to the sign of the 
argument 

Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there is a small interval at each end of the domain in which 
the result is liable to be contaminated with error however since both 
domain and range are bounded the absolute enxtr in the result cannot be 
large. 

2) By step 1 , the Identity sin'^fr) = rt/2 - 2 sin"^{v'(1-j:)/2)) is preserved. 

ACQS 
DACOS 

REAL32 FUNCTION ACQS (VAL REAL32 X) 
REAL64 FUNCTION DACOS (VAL REAL64 X) 

Compute cosine'ipo (in radians). 

Domain: [-1.0,1.01 

Range: [Q,Pi\ 

Primary Donriain: [-0.5, 0.5] 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 

Propagated Error 

A = -X/y/1 -Jfi, R = -A/(sin-i(:so yi -Jt2) 

Generated Error 

Primary Domain [-1-0, 1.0] 

MRE RMSRE MAE RMSAE 

Single Length: 1.06 ulp 0.38 ulp 2.37 ulp 0.61 ulp 

Double Length: 0.96 ulp 0.32 ulp 2.25 ulp 0.53 ulp 

The Algorithm 

1 If |;q > 0.5, set Xwork:= SQRT ((1 - \X\)/2) . Compute RwoHc - 
arcsine(2 * Xwork) with a floating-point rational approximation. If the 
argument was positive, this is the result, othenYise set the result = Pi 
" Rwork. 
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2 Otherwise compute Rwork directly using the rational approximation. 
If the argument was positive, set result = Ull - Rwork, otherwise 
Tesun=HI2+ Rwork. 

Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there is a small interval at each end of the domain in which 
the result is liable to be contaminated with error, although this interval is 
larger near 1 than near --1 , since the function goes to zero with an infinite 
derivative there. However since both the domain and range are bounded 
the absolute error in the result cannot be large. 

2) Since the rational approximation is the same as that in asin, the relation 
cos-i(i) = 7cJ2- sin~iW 's preserved. 



ATAN 
DAIAN 

REAL32 FUNCTION ATAN (VAL REAL32 X) 
REAL64 FUNCTION DATAH (VAL KEAL64 X) 

Compute tan-^(^ (in radians). 

Domain: (-Inf. '"f] 

Range: \-PU2,Pil2] 

Primaty Domain: [-7, z], z = 2 - ^3 = 0.2679 

Exceptions 
None, 
Propagated Error 

A'XI{\ +J?),if=J¥7{tan-i{;^(1 +^)) 

Generated Error 

Primary Domain Em)r MRE RMSRE 
Single Length: 0.56 ulp 0.21 ulp 

Double Length: 0,52 ulp 0.21 ulp 

The Algorithm 

1 \\(Xi> 1.0, seXXwork - V\X\ , otherwise Xwoik = \Xl, 

2 \fXwork > 2-v^3, set F = ^work*^3 -1 ygCwork +^3), othenwise F 
= Xwork. 
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3 Compute Rwork = arctan(J^ wth a floating-point rational approxima- 
tion* 

4 \fXworky/as reduced in (2), seti? =PifS +Rworky otherwise/? =Rwork. 

5 If Z was reduced in (1), set RESULT = Pif2-R, otherwise RESULT 
= R. 

6 Set the sign of the RESULT according to the sign of the argument 
Notes 

1) For|X| >ATTnaxt Itan'^C^I is indistinguishable from Jt/2 in the floating- 
point format. For single-length, ^rwwx = 1.68*10^, and for double-length 
ATmax = 9*10^^, approximately. 

2) This function is numerically very stable, despite the complicated argu- 
ment reduction. The worst en'ors occur just above 2-^/3, but are no more 
than 3.2 ulp. 

3) It is also very well behaved with respect to errors in the argument, i.e. 
the en'or ampllflcation factors are always small. 

4) The argument reduction scheme ensures that the identities tan~^QC) = 
jtI2 - ian-HVX), and tan-i(;f) - 7iI6 + tan-H(y3*A'"1)/(v'3 + X)) are 
preserved. 

ATAN2 
DATAN2 

REAL32 FUNCTION ATAK2 (VAL REAL32 X, Y) 
REAL64 FUNCTION DATAN2 {VAL RE1AL64 X, Y) 

Compute the angular co-ordinate tan~^(l:7^ (in radians) of a point whose 
A' and Yco-onJinates are given. 

Domain: [-Inf, Inf] x Hnf , Inf] 

Range: {-PirPi\ 

Primary Donnain: See note 2. 

Exceptions 

(0, 0) and (±lnf,±lnf) give undefined.NaN. 

Propagated Error 

A=X('\± Y)I{Jfi + y2), R=X{^ ± Y)f{tan-Hy7X){^ + 1^)) (See note 3) 
Generated Error 
See note 2. 

72 TDS 368 01 March 1993 



1 The Occam libraries 11 

The Algorithm 

1 If JST, the first argument, is zero, set the result to ± :i /2, according to 
the sign of Y, the second argument. 

2 Otherwise set EwoTk- ATAN [YIX) . Then if y < set RESULT = 
Rwork - Pf, othenwise set RESULT -Pi- Rw<»ic. 

Notes 

1) This two-argument function Is designed to perform rectangular-to-polar 
co-ordinate conversion. 

2) See the notes for ATAN for the primary domain and estimates of the 
generated error 

3) The en-or amplification factors were derived on the assumption that the 
relative error in y is ± that mX, otherwise there would be separate factors 
for JP and Y They are small except near the origin, where the potar co-ordi- 
nate system is singular. 

SINH 
DSINH 

BEAL32 FUNCTION SINH {VAL REAL32 X) 
PEAL64 FUNCTION DSINH (VAL REAL64 X) 

Compute sin/i(^. 

Domain: l-Hmax, Hmax] = [-^9.4, 89.4]S, 1-710.5. 710.5]D 
Range: (-Inf, inf) 

Primary Domain: (-1 .0, 1 .0) 

Exceptions 

X < -Hmax gives -Inf, and X > Hmax gives Inf. 

Propagated Error 

A =J^cosh(;f). -R =ArcothC30 {See note 3) 
Generated Error 

Primary Domain [^.Q,XBig] (See note 2) 

IVIRE RMSRE MAE RMSAE 

Single Length: 0.91 ulp 0.26 ulp 1.41 ulp 0.34 ulp 

Double Length: 0.67 ulp 0.22 ulp 1.31 ulp 0.33 ulp 

The Algorithm 

1 lf|fl>JCffi^, set/6w)rfe:=KXP(l^-[n(2)). 
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2 \tXBig^ V^^'\.0,sei\er[\p'=EXS{\X\),an<ise{Rwork={temp- 
Vtempyi. 

3 Otherwise compute smh{tY|) with a floating-poi nt rational approxima- 
tior\. 

4 In all cases, set RESULT = ± Rwork according to the sign of JST. 
Notes 

^)Hmax is the point at which sinhp:) becomes too large to be represented 
in the floating-point format. 

2)XBig is the point at which e^l^ becomes insignificant compared wth e\^^ 
(in floating-point). For single-length it is 8,32, and for double-length it Is 
18.37. 

3) This function is quite stable with respect to errors in the argument. Rela- 
tive error is magnified near zero, but the absolute en-or is a better measure 
near the zero of the function and it is diminished there. For large arguments 
absolute en-ors are magnified, but since the function is itself large, relative 
error is a better criterion, and relative errors are not magnified unduly for 
any argument in the domain , although the output does become less reliable 
near the ends of the range. 

COSH 
DCOSH 

REAL32 FUNCTION COSH (YAL REAL32 X) 
REAL64 FUNCTION DCOSH (VAL REAL64 X) 

Compute cosh(Al. 

Domain; [-Hmw[,Hmax] = [-89.4, 89.4]S, [-710.5, 710.5]D 

Range: [1.0, Inf) 

Primary Domain: [-XBig, XBig]^ [-8.32, 8.32]S 

= [-18.37, 18.37]D 

Exceptions 

1^ > Umax gives Inf, 

Propagated Error 

A=Xs\r)h{?0 , J?=jrtanhP0 (See note 3) 
Generated Error 

Primary Domain En-or MRE RMS 
Single Length: 1 24 ulp 0.32 ulp 

Double Length: 1.24 ulp 0.33 ulp 
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The Algorithm 

2 Otherwise, set temp = EXP ( j;?] ) , and set result = {temp + Vtemp)f2. 

Notes 

1 ) Ibnax is the point at wh ich coshp^ becomes too large to be represented 
in the floating-point format. 

2)XBig is the point at which e ~^ becomes insignificant compared with el-^ 
(in floating-point), 

3) En'ors in the argument are not seriously magnifiecf by this function, 
although the output does become less reliable near the ends of the range. 

TANH 
OTANH 

REAL32 FUNCTION TANH (VAL REAL32 X) 
REAL64 FUNCTION DTANH (VAL F£AL64 X) 

Compute tainhQO- 

Domain: H^t ^^^ 

Range: H-0. 10] 

Primary Domain: [-Log(3)/2. Loo(3)/2] = [-0.549, 0.549] 

Exceptions 

None. 
Propagated Error 

A = A7cosh2(X). R = JK/sinhtX) cosh(:¥) 
Generated Error 

Primary Domain Error MRE RMS 
Single Length: 0.53 ulp 0.2 ulp 

Double Length: 0.53 ulp 0.2 ulp 

The Algorithm 

1 If pq > ln(3)/2, set t€mp:= EXP {[^2) . Then set 
Rwork-l-TJiUtemp). 

2 Otherwise compute Rwork = tanh(i:?l) with a floating-point rational 
approximation. 
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3 In both cases, set RESULT = ± Rwork according to the sign of X 
Notes 

1) As a floating-point number, tanh(^ becomes indistinguishable from its 
asymptotic values of ±1 .0 for \K\> HTmax, where HTmax is 8.4 for single- 
length, and 19.06 for double-iength. Thus the output of tank is equal to 
±1.0 for such X 

2) This function is very stable and well-behaved, and en^ors in the argument 
are always diminished by it. 



ElAN 
DRAN 



RE:AL32,INT32 FUNCTION RAN (VAL INT32 X) 
B£:AL64fINT64 FUNCTION DRAN (VM. INT64 X) 

These produce a pseudo-random sequence of integers, or a corre- 
sponding sequence of floating-point numbers between zero and one. X is 
the seed integer that initiates the sequence. 



Domain: 


Integers (see note 1) 


Range: 


[0.0, 10] X Integers 


Exceptions 




None. 





The Algorithm 

1 Produce the next integer in the sequence: JVi+j = (aAt + 1 WdJi/ 

2 Treat Nk+2 as a fixed-point fraction in [0,1), and convert it to floating 
point. 

3 Output the floating point result and the new integer. 
Notes 

1) This function has two results, the first a real, and the second an integer 
(both 32 bits for single-length, and 64 bits for double-length). The integer 
is used as the argument for the next call to RAN, i.e. it 'canies' the pseudo- 
random linear congruential sequence 7^, and it should be kept in scope for 
as long as RAN is used. It should be initialized before the first call to ran 
but not modified thereafter except by the function itself, 

2) If the integer parameter is initialized to the same value, the same 
sequence (both floating-point and integer) will be produced. If a different 
sequence is required for each mn of a program it should be ini^alized to 
some 'random' value, such as the output of a timer. 
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3) The integer parameter can be copied to another variable or used in 
expressions requiring random integers. The topmost bits are the most 
random. A random integer in the range [0^] can conveniently be produced 
by taking the remainder by (L+1) of the integer parameter shifted right by 
one bit. If the shift Is not done an integer in the range [-LJL] will be 
produced. 

4) The modulusMis 2^^ for single-length and 2^ for double-length, and the 
multipliers, a, have been chosen so that all M integers will be produced 
before the sequence repeats. However several different integers can 
produce the same floating-point value and so a floating-point output may 
be repeated, although the sequence of such will not be repeated until M 
calls have been made. 

5) The floating-point result is uniformly distributed over the output range, 
and the sequence passes various tests of randomness, such as the 'run 
test', the 'maximum of 5 test' and the 'spectral test'. 

6) The double-length version is slower to execute, but 'more random' than 
the single-length version. If a highly-random sequence of single-length 
numbers is required, this could be produced by converting the output of 
DRAH to single-length. Conversely If only a relatively crude sequence of 
double-length numbers is required, RAN could be used for higher speed 
and its output converted to double-length. 

1.4.3 IMS T400/r414/T425n'426 elementary function library 

To use this library a pnsgram header must include the line: 

#OSE "tbmaths.lib'' 

The version of the library described by this section has been written for 32-bit 
processors without hardware for floating-point arithmetic. Functions from it will 
give results very dose, but not identical to, those produced by the con^sponding 
functions from the single and double length libraries. 

This is the version speciflcally intended to derive maximum performance from the 
IMS T400, T414, T425, and T426 processors. The single-precision functions make 
use of the FMOL instruction available on 32-btt processors without floating-point 
hardware. The library is compiled for transputer class TB. 

The tables and notes at the beginning of section 1 .4 apply equally here. However 
all the functions are contained in one library. 

Function definitions 



ALOG 
DALOG 



REAL32 FDNCTION ALOG {YAL REAL32 X) 
REAL64 FUNCTION DALOG (VAL REAL64 X) 
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These compute: logtrW 

Domain: (Q,XMAX\ 

Range: |WrnZ^, MaxLog] (See note 2) 

Primary Domain: [y2/2, v'2) = [0.7071, 14142) 

Exceptions 

All arguments outside the domain generate an undeflned.NaN. 
Propagated Error 

^s1, R=\QQe{X) 

Generated Error 

Primary Domain En'or MRE RMSRE 
Single Length: 1.19 ulp 0.36 ulp 

Double Length: 2.4 ulp 1.0 ulp 

The Algorithm 

1 Split X into its exponent N and frac^on F. 

2 Find the natural log of JF' with a fixed-point rational approximation^ and 
convert it into a floating-point number LnF. 

3 Compute ln(2) * AT with extended precision and add it to LnF to get 
the result. 

Notes 

1) The tenn ln{2) * JVis much easier to compute (and more accurate) than 
LnF, and it is larger provided N is not (i.e. for arguments outside the 
primary domain). Thus the accuracy of the result improves as the modulus 
of log (^increases, 

2) The minimum value that can be produced, MinLog, is the logarithm of 
the smallest denormalized floating-point number. For single length MinLog 
is -1 03.28, and for double length it is --744.4. The maximum value MaxLog 
is the logarithm ofXMAX. For single-length it is 88.72, and for double- 
length it is 709.78. 

3) Since Inf is used to represent a// values greater than Jdi^4;srits logarithm 
cannot be defined. 

4) This function is well-behaved and does not seriously magnify en"ors in 
the argument 
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ALOGIO 
DALOGIO 

REAL32 FtJKCTION ALOGIO (VAL lt£AL32 X) 
REAL64 FDNCTION DALOGIO (VAL R£ALe4 X) 

These compute: log-iot^ 

Domain: {0,XMAX\ 

Range: [WmLIO, MaxLIO] (See note 2) 

Primary Domain: [y2/2, ^2) = [0.7071, 1.4142) 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 
Propagated Error 

-4 s ioQioW, Ji = logio(e)/Ioge(a:) 
Generated Error 

Primary Domain En-or MRE RIUISRE 
Single Length: 1 .43 ulp 0.39 ulp 

Double Length: 2.64 ulp 0.96 ulp 

The Algorithm 

1 Set fCTnp;=ALOG(X)- 

2 \ftemp is a NaN, copy it to the output, otherwise set 
resutt = log(e) * remp. 

Notes 

1) See note 1 for ALOG. 

2) The minimum value that can be produced, MinLIO, is the hase-10 loga- 
rithm of the smallest denonnalized floating-point number. For single length 
MinL^O is -44.85, and for double length It is -323.3. The maximum value 
MaxLIO is the base-10 logarithm o^XMAX. For single length MaxL^O is 
38.53, and for double-length it is 308.26. 

3) Since Inf is used to represent a// values greater than.S31iS:its logarithm 
cannot be defined. 

4) This function is well-behaved and does not seriously magnify emars in 
the argument. 
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EXP 

DEXP 

REAL32 FnfK:TION EXP (VAL HEAL32 X) 
REAL64 FUNCTION DEXP (VAL REAL64 X) 

These compute: e^ 

Domain: [-M.MaxLog) = [-Jnf, 88.03)S, Hnf, 709.78)D 

Range: [0, Inf) (See note 4) 

Primary Domain: {-Ln2l2, Ln2I2) = [-0.3466, 0.3466) 

Exceptions 

All arguments outside the domain generate an Inf. 
Propagated Error 

Generated Error 

Primary Domain En-on MRE RMSRE 
Single Length: 0.51 ulp 0.21 ulp 

Double Length: 0.5 ulp 0.21 ulp 

The Algorithm 

1 SetJV= Integer part of ^n(2). 

2 Compute the remainder of JTby ln(2), using extended precision arith- 
metic. 

3 Convert the remainder to fixed-point, compute its exponential using 
a fixed-point rational function, and convert the result back to floating 
point, 

4 Increase the exponent of the resutt by^. If ^is sufficiently negative 
the result must be denormalized. 

Notes 

1) MaxLog Is io^gOLiX), 

2) The analytical properties of e^maite the relative em)r of the result propor- 
tional to the absolute en^or of the argument. Thus the accuracy of step 2, 
which prepares the argument for the rational approximation, is cnjcial to 
the performance of the subroutine. It is completely accurate v/hen N=0, 
i.e. in the primary domain, and becomes less accurate as the magnitude 
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of ?/ increases. Since N can attain larger negative values than positive 
ones, £XP is least accurate for large, negative arguments. 

3) For sufficiently negative arguments (below -87.34 for single-length and 
belcw -708.4 for double-length) the output is denormalized, and so the 
floating-point number contains progressively fewer significant digits, which 
degrades the accuracy. I n such cases the em^r can theoretically be a factor 
of two. 

4) Although the true exponential function is never zeK>, for large negative 
arguments the tme result becomes too small to be represented as a float- 
ing-point number, and EXP underflows to zero. This occurs for arguments 
below -103.9 for single-length, and below -745.2 for double-length. 

5) The propagated error is considerably magnifled for large positive argu- 
ments, but diminished for large negative arguments. 



POHER 
DPOfiER 

REAL32 FONCTION POWER (VAL REAL32 X, Y) 
REAL32 FUNCTION DFOWESl (VAL REAL64 X, Y) 

These compute: JT^ 

Domain: [0, tnf] x [-inf, Inf] 

Range: (-Inf. Inf) 

Primary Domain: See note 3. 

Exceptions 

Ifthe first argument is outside its domain, undefined.NaN isretumed. If the 
true value of J?r*'exceeds;tM;4;srjnf is retu med In certai n other cases oth er 
NaNs are produced: See note 2. 

Propagated Error 

A = yX^{^±\OQe{X)l iE = Yl1±log.(30)(Seenote4) 

Generated Error 

Example Range Error MRE RMSRE (See note 3) 
Single Length: 10 ulp 0,24 ulp 

Double Length: 13.2 ulp 1J3 ulp 

The Algorithm 

Deal with special cases: either argument = 1,0, +lnf or -Inf (see note 2). 
Otherwise: 
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(a) For single precision: 

1 Compute L = Iog2p0 in fixed point, where X is the first argument 

2 Compute W= 7 x L in double precision, where Y\s the second argu- 
ment. 

3 Compute 2'*' in fixed point and convert to floating-point result, 

(b) For double precision: 

1 ComputeL = Iog2y0inextendedprecision, whereXisthefirstargu- 
ment. 

2 Compute W-YxL\x\ extended precision, where Y is the second 
argument. 

3 Compute RESULT = 2^ '\w extended precision. 
Notes 

1) This subroutine implements the mathematical function x?* to a much 
greater accuracy than can be attained using the ALOG and EXP functions, 
by perfonning each step in higher precision. 

2) Results for special cases are as follows: 



First Input (X) 


Second Input (Y) 


Result 


<0 


ANY 


undeflned.NaN 





£0 


undefined.NaN 





kY^XMAX 








Inf 


unstable.NaN 


<A'<1 


Inf 





<X<\ 


-Inf 


Inf 


1 


-XMAX^Y-^XMAX 


1 


1 


± Inf 


unstable.NaN 


1 <X^XMAX 


Inf 


Inf 


1 <X<.XMAX 


-Inf 





Inf 


1 ^ y £ Inf 


Inf 


Inf 


-Inf ^y 5-1 





Inf 


-1 <y<i 


undefined.NaN 


otherwise 





1 


othentfise 


1 


X 



3) Perfonning all the calculations in extended precision makes the double- 
precision algorithm very complex in detail, and having two arguments 
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makes a primary domain difficult to specify. As an indication of accuracy, 
the functions were evaluated at 100 000 points logarithmically distributed 
over (0,1, 10.0), with the exponent iineariy distributed over (-35.0, 35.0) 
(single-length), and (-300.0, 300.0) (double-length), producing the errors 
given above. The errors are much smaller if the exponent range is reduced. 

4) The error amplification factors are calculated on the assumption that the 
Illative error in y is ± that \nX, otherwise there would be separate factors 
for both X and y; It can be seen that the propagated en-or will be greatly 
amplified whenever log^(Jt) or 7 is large. 

The Algorithm 

1 Compute L = iogiCJf) in fixed point, where X is the first argument. 

2 Compute W= Y x L in double precision, where Y'\s the second argu- 
ment. 

3 Compute 2**" in fixed point and convert to floating-point result 

4 Compute L = log2(^ in extended precision, where JST is the first argu- 
ment. 

5 Compute JF= Y x L in extended precision, where Y is the second 
argument 



SIN 
DSIH 



6 Compute i?E5ULr=2'*^in extended precision. 



R£AL32 FDKCTION SIN (VAL REM.32 X) 
R&AL64 FUNCTION DSIN (VAL REAL64 X) 

These compute: sme{X} (where X is in radians) 

Domain: [Smax, Smax] = [-12868.0, 12868.0]S, 

= ["2.1*108, 2.1*10»1D 

Range: [-10,1-0] 

Primary Domain: [-PU2, Pif2] = [-1 .57, 1 ,57] 

Exceptions 

All arguments outside the domain generate an InexactNaN, except ± Inf, 
which generates an undeflned.NaN. 

Propagated Error 

A=XcospO, i?=Xcot(AO 
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Generated Error (See note 3) 

Range; Primary Domain 10, 2Fi\ 

MRE RMSRE MAE RMSAE 

Single Length: 0.65 ulp 0.22 ulp 0.74 ulp 0.18 ulp 

Double Length: 0.56 ulp 0.21 ulp 0.64 ulp 0.16 ulp 

The Algorithm 

1 Set JV = integer part of \X\/Fi. 

2 Compute the remainder of \X\ by/Y, using extended precision arith- 
metic. 

3 Convert the remainder to fixed-point, compute its sine using a fixed- 
point rational function, and convert the result back to floating point. 

4 Adjust the sign of the result according to the sign of the argument and 
the evenness of JV. 

Notes 

1) For arguments outside the primary domain the accuracy of the result 
depends cnjcially on step 2, the eidended precision corresponds to K 
extra bits in the representation of :t (AT = 8 for single-length and 12 for 
double-length). If the argument agrees with an integer multiple of jc to more 
than K bits there is a loss of significant bits in the remainder^ equal to the 
number of extra bits of agreement, and this causes a loss of accuracy in 
the result. 

2) The extra precision of step 2 is lost if JV becomes too large, and the cut-off 
Sttwx is chosen to prevent this. In any case for large arguments the 'granu- 
larity' of floating-point numbers becomes a significant factor For argu- 
ments larger than Smax a change in the argument of 1 ulp would change 
more than half of the significant bits of the result, and so the result is consid- 
ered to be essentially indeterminate. 

3) The propagated error has a complex behavior. The propagated relative 
error becomes large near each zero of the function (outside the primary 
range), but the propagated absolute error only becomes large for large 
arguments. In effect, the en^or is seriously amplified only in an interval about 
each irrational zero, and the width of this interval increases roughly in 
proportion to the size of the argument. 

4) Since only the remainder of Xby Pi is used in step 3, the symmetry sin(x+ 
nji;) = ±sin(x) is preserved, although there is a complication due to differing 
precision representations of a. 

5) The output range is not exceeded. Thus the output of SIN is always a 
valid argument for AS IN. 
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COS 
DCOS 



REAL32 FUNCTION COS (VAL REAL32 X) 
REAL64 rONCTION DCOS (VAL REAL64 X) 

These compute: cosine (^ (where ^ is in radians) 

Domain: [Snuix, Smax] = [-12868.0, 12868.0]S, 

= [-2.1*10»,2.1*10S]D 

Range: [-10,1.0] 

Primary Domain: See note 1. 

Exceptions 

All arguments outside the domain generate an inexact.NaN, except dzlnf, 
which generates an undefJned.NaN. 

Propagated Error 

A = -JSrsin(ar), R - -JT tant?) (See note 4) 
Generated Error 

Range: lOJH/4) [0, 2Fi\ 

MRE RMSRE MAE RMSAE 

Single Length: 1.0 ulp 0.28 ulp 0,81 ulp 0.17 ulp 

Double Length: 0.93 ulp 0.26 ulp 0.76 ulp 0.18 ulp 

The Algorithm 

1 Set JV = integer part of {\X\+im)IPi. 

2 Compute the remainder of{\X\+PU2) by Pi, using extended precision 
arithmetic. 

3 Compute the remainder to fixed-point, compute its sine using a fixed- 
point rational ftjndion, and convert the result bade to floating point. 

4 Adjust the sign of the result according to the evenness of iV. 
Notes 

1) Inspection of the algorithm shows that argument reduction always 
occurs, thus there is no 'primary domain' for COS. So for all arguments the 
accuracy of the result depends caiciaily on step 2. The extended precision 
con-esponds toATextra bits in the representation of ji {K= 8 forsingle-length 
and 12 for double length). If the argument agrees with an odd integer 
multiple of n/2 to more than K bits there is a loss of significant bits in the 
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remainder, equal to the number of extra bits of agreement, and this causes 
a ioss of accuracy in the result. 

2) The extra precision of step2 Is iost if ^becomes too large, and the cutoff 
Smw: is chosen to prevent this, [n any case for large arguments the *granu- 
larity' of floating-point numbers becomes a significant factor. For argu- 
ments larger than Smax a change in the argument of 1 ulp would change 
more than half of the significant bits of the result, and so the result is consid- 
ered to be essentially indeterminate. 

3) For small arguments the en^rs are not evenly distributed. As the argu- 
ment becomes smaller there is an increasing bias towards negative en^ors 
(which is to be expected from the form of the Taylor series). For the single- 
length version and A' in [-0.1, 0.1], 62% of the errors are negative, whilst 
forXin [-0.01, 0.01], 70% of them are. 

4) The propagated error has a complex behavior. The propagated relative 
error becomes large near each zero of the function, but the propagated 
absolute error only becomes large for large arguments. In effect, the error 
is seriously amplified only in an interval about each irrational zero, and the 
width of this interval increases roughly in proportion to the size of ^e argu- 
ment. 

5) Since only the remainder of {\X\^PiI2) by Pi Is used in step 3, the 
symmetry cos(r»- njt ) = ± cosfr) is preserved. Moreover, since the same 
rational approximation is used as in SIN, the relation cosW =sin(r^■ ji/2) is 
also preserved. However, in each case there is a complication due to the 
different precision representations of 35. 

6) The output range is not exceeded. Thus the output of cos is always a 
valid argument for ACQS. 

TAN 
DTAN 

RiIiLL32 FONCTION TAN (VAL REAL32 X) 
RSAL64 FUNCTION DTAN (VAL R£AI64 X) 

These compute: tan(A!) (where AT is in radians) 

Donnain: [-Tmax, Tmax] = [-6434,0, 6434.0]S 

= [-1.05*10», 1.05*10»|D 
Range: (-Inf, Inf) 

Primary Domain: [-ft74,i^74] = [-0.785, 0.785] 

Exceptions 

All arguments outside the domain generate an InexactNaN , except =b Inf, 
which generate an undefined.NaN. Odd integer multiples of Td2 may 
produce unstable.NaN. 
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Propagated Error 

A = X{^■^ tan^CX)), R=X{U tan2pO)/tantX) (See note 4) 
Generated Error 

Primary Domain Error MRE RMSRE 
Single Length: 3.5 ulp 0.23 ulp 

Double Length: 0.69 ulp 0.23 ulp 

The Algorithm 

1 SetAr= integer part of ^(Ptf2). 

2 Compute the remainder of X by iV2, using extended precision arith- 
metic. 

3 Convert the remainder to fixed-point, compute its tangent using a 
fixed-point rational function, and convert the result back to floating 
point. 

4 if ^ is odd, take the reciprocaL 

5 Set the sign of the result according to the sign of the argument 
Notes 

1) R is large whenever A" is near to an integer multiple of JiI2, and so tan 
is very sensitive to small en-ors near its zeros and singularities. Thus for 
arguments outside the primary domain the accuracy of the result depends 
cmcially on step 2. The extended precision corresponds to A" extra bits in 
the representation of 7i/2 ^= 8 for single-length and 12 for double-Iengfli). 
If the argument agrees with an Integer multiple of 3t/2 to more than K bits 
there is a loss of significant bits in the remainder, approximately equal to 
the number of extra bits of agreement, and this causes a loss of accuracy 
In the result. 

2) The extra precision of step 2 is lost if JV becomes too large, and the cut-off 
Thiax is chosen to prevent this. In any case for large arguments the 'granu- 
larity' of floating-point numbers becomes a significant factor. For argu- 
ments larger than Tmax a change in the argument of 1 ulp would change 
more than half of the significant bits of the result, and so the result is consid- 
ered to be essentially indeterminate, 

3) Step 3 of the algorithm has been slightly modified in the double-precision 
version from that given in Cody & Waite to avoid fixed-point underflow in 
^e polynomial evaluation for smalt arguments. 

4) Tan is quite badly behaved with respect to en-ors in the argument. Near 
its zeros outside the primary domain the relative error is greatly magnified, 
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though the absolute error is only proportional to the size of the argument. 
In ef act, the error i$ seriously amplified in an interva} about each irrational 
zero, whose width increases roughly in proportion to the size of the argu- 
ment. Near its singularities both absolute and relative errors become large, 
so any large output from this function is liable to be seriously contaminated 
with error, and the larger the argument, the smaller the maximum output 
which can be trusted. If step 4 of the algorithm requires division by zero, 
an unstable.NaN is produced instead. 

5) Since only the remainder of X by PiI2 is used in step 3, the symmetry 
tan(r(- njc] = tan(x) is preserved, although there is a complication due to the 
differing precision representations of rc. Moreover, by step 4 the symmetry 
tan{x) = 1/ tan( rt/2 -x) is also preserved. 

AS IN 
DAS IK 

REAL32 FUNCTION ASIN (VAL REAL32 X) 
REAL64 FUNCTION DASIN (VAL REAL64 X) 

These compute: sin~^(X) (in radians) 

Domain: [-10, 1.0] 

Range: [-iW2, PUT] 

Primary Domain: [-0.5, 0.5] 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 
Propagated Error 

Generated Error 

Primary Domain [-1 .0, 1 .0] 

RARE RMSRE MAE RMSAE 

Single Length: 0.53 ulp 0.21 ulp 1.35 ulp 0.33 ulp 

Double Length: 2.8 ulp 1.4 ulp 2.34 ulp 0.64 ulp 

The Algorithm 

1 lflfl>0.5,setJS:H'or;fc:=SQRT((1^lfl)/2). 

Compute Rwork = arcsine(-2 * Xwork) with a floating-point rational 
approximation^ and set the result = Rwork + Fill. 

2 Otherwise compute the result directly using the rational approxima- 
tion. 
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3 In either case set the sign of the result according to the sign of the 
argument. 

Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there is a small intefval at each end of the domain in which 
the result is liable to be contaminated with error: however since both 
domain and range are bounded the absolute error in the result cannot be 
large. 

2) By step 1 , the identity sin-^W = k/2 - 2 s\r\-Hy/{Ux)/2)) is preserved, 

ACQS 
DACOS 

REAL32 FUNCTION ACOS (VAL REAL32 X) 
REAL64 FUNCTION DACOS (VAL REAL64 X) 

These compute: cosine~^(^ (in radians) 

Domain: [-1.0,10] 

Range: [0, Pi\ 

Primary Domain: [-0,5, 0.5] 

Exceptions 

All arguments outside the domain generate an undefined.NaN. 

Propagated Error 

^=-J£/yi-J^, i? = -A'/(sin-iC:t)v'1-A2) 

Generated Error 

Primary Domain 1-1 .0, 1 .0] 

MRE RMSRE MAE RMSAE 

Single Length: 1.1 ulp 0.38 ulp 2.4 ulp 0.61 ulp 

Double Length: 1.3 ulp 0.34 ulp 2.9 ulp 0.78 ulp 

The Algorithm 

1 If psn > 0-5. seiXwork- SQRT ((1- \X\)f2] , CompuieRwork-arcsme 
(2 • Xwork) with a floating-point rational approximation. If the argu- 
ment was positive, this Is the result, othenvise set the result = Pi- 
Rwo^, 

2 Otherwise compute Rwork directly using the rational approximation. 
If the argument was positive, set result = Pill - Rwork, olhenvise 
resu\i = PiI2-*- Rwork. 
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Notes 

1) The error amplification factors are large only near the ends of the 
domain. Thus there is a srnaK interval at each end of the domain in which 
the result is liable to be contaminated with error, although this interval is 
larger near 1 than near-1, since the function goes to zero wrth an infinite 
derivative there. However since both the domain and range are bounded 
the absolute error in the result cannot be large. 

2] Since the rational approximation is the same as that in AS IN, the relation 
cos"^(x) = ji/2 - sin"^Mis preserved. 



ATAN 
DATAN 

REAL32 FUNCTION ATAN {VAL REAL32 X) 
REAL64 FUNCTION DATAN (VAL REAL64 X) 

These compute: tan-i(^ (in radians) 

Domain: [-Inf, Inf) 

Range: 1-Pif2, Pi/2] 

Primary Domain: [-z, z], z = 2-y/3 = 0.2679 

Exceptions 

None, 

Propagated Error 

Generated Error 

Primary Domain En-or MRE RMSRE 
Single Length: 0.53 ulp 0.21 ulp 

Double Length: 1.27 ulp 0.52 ulp 

The Algorithm 

1 If i:q > 10, seiXwork = 1/|A1, otherwise Zwo/ifc = \X\. 

2 \fXwork>2-yZ, seiF={Xwork*^Z--1)I{Xwoj^+V3), otherwise? 
= Xwork. 

3 Compute Rwork = arctan(F) with a floating-point rational approxima- 
tion. 

4 IfXwoikwas reduced in (2), se\R=PilS -^Rwork, otherwise J? =Rwork, 
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5 IfJf was reduced in (1), set RESULT = PiI2 - R, oihemise RESULT 
= R. 

6 Set the sign of the RESULT according to the sign of the argument. 
Notes 

1) For 1^1 >ATmax, |tan"^(X)| is indistinguishable from rt/2 in the floating- 
point format. For single-length, j47>nflar= 1.68*10'^, and for double-length 
ATmax = 9*10^*, approximately. 

2) This function Is numerically very stable, despite the complicated argu- 
ment reduction. The worst en"ors occur just above 2-^Z, but are no more 
than 1 .8 ulp. 3) It ts also very well behaved with respect to enters in the argu- 
ment, i.e. the enor amplification factors are ahA/ays small, 

4) The argument reduction scheme ensures that the identities tan'^pO ~ 
nil - tan-i(1/-^, and tan-i(;t) = n/5 + tan"i((v'3*;sr"l)/(y3 + X)) are 
preserved. 

ATJIH2 
DATJUI2 

It£AL32 FUNCTION ATAN2 (VAL REAL32 X, Y] 
RKAX.64 FUNCTION DATAN2 (VAL REAL64 X, Y) 

These compute the angular co-ordinate \ar\~^YIX) {In radians) of a point 
whose JSTand Yco-ordlnates are given. 

Domain: [-inf, Inf] x Hnf, lnf| 

Range: (-Pi, Pil 

Primary Domain: See note 2. 

Exceptions 

(0, 0) and (±lnf,±lnf) give undeflned.NaK. 

Propagated Error 

A'Ja^±Yiii^ + y^), R=X(^ ±m^r\-HYfX){X^ + l^}) (SeenoteS) 

Generated Error 

See note 2. 

The Algorithm 

1 If A', the first argument, is zero, set the result to ± Jt/2, according to 
the sign of t; the second argument. 
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2 Othefwise set Rwork- ATAN{i7^ . Then if Y < set RESULT = 
Rwork - Pi, othenvise set RESULT = Pi- Rwork. 

Notes 

1) This two-argument function is designed to perform redangular-to-polar 
co-ordinate conversion, 

2) See the notes for atan for the primary domain and estimates of the 
generated en'or 

3) The error amplification factors were derived on the assumption that the 
rela^ve en*or in y is ± that \nX, otherwise there would be separate factors 
for A" and y They are small except near the origin, wrfiere the polar co-ordi- 
nate system is singular. 

SINH 
DSINH 

REAL32 FUNCTION SINH (VAL REAL32 X) 
REAL64 FDKCTION DSIKH (VAL REAL64 X} 

These compute: sinhpQ 

Domz\n:l-Hmax, Hmax] = [-89,4, 89.4]S, [-710.5, 710.5]D 
Range: (-Inf, Inf) 

Prinnary Domain: (-1-0, 1.0) 

Exceptions 

X < -Hmax gives -Inf, and X > Hmwc gives Inf. 

Propagated Error 

A-X cosh(Jt), i? = Z coth(X) (See note 3) 

Generated Error 

Primary Domain [1 .0, XBig] 
(See note 2) 

MRE RMSRE MAE RMSAE 

Single Length: 0.89 ulp 0.3 ulp 0.98 ulp 0.31 ulp 

Double Length: 1.3 ulp 0.51 ulp 1.0 ulp 0.3 ulp 

The Algorithm 

1 ^\X\>XBig,^e\Rwork\-t::^^{\X\-\r\{2)). 

2 MXBig ^\X\^ 1.0. set temp:- EXP (|A1) , and set 
Rwork = {femp - Vt€mp)l2. 
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3 Otherwise compute Rwork = sinhd^i) with a fixed-point rational 
approximation. 

4 In all cases, set RESULT = ± Rwork according to the sign of X 

Notes 

1 ) Hnua is the poi nt at which slnh(^ becomes too large to be represented 
in the floating-point format. 

2)XBig is the point at which e ~^ becomes Insignificant compared with cl-^, 
(in floating-point). For single-length it is 8.32, and for double-length it is 
18.37. 

3) This function is quite stable with respect to errors in the argument. Rela- 
tive error is magnified near zeroj but the absolute en-or is a better measure 
near the zero of the function and It is diminished there. For large arguments 
absolute en-ors are magnified, but since the function Is itself large, relative 
enror is a better criterion, and relative en'ors are not magnified unduly for 
any argument In the domain, although the output does become less reliable 
near the ends of the range. 

cosa 

DCOSH 

REAL32 FUNCTION COSH (VAL REAL32 X) 
R£AL64 FDNCTIOH DCOSH (VAL REAL64 X] 

These compute: cosh{30 

Domain; [-Hmax, HTnax] = [-89.4, 89.4]S, [-710.5, 710.5]D 

Range: [1.0, Inf) 

PrimaryDomaIn: l-XBig, XBig] = [-8.32, 8.32]S 

= [-18.37, 18.37]D 

Exceptions 

i;^ > Hrmx gives Inf. 
Propagated Error 

^ =Zsinh(X) , R =X\3nh(X) {See note 3) 

Generated Error 

Primary Domain En-or MRE RMS 
Single Length: 0.99 ulp 0,3 ulp 

Double Length: 1.23 ulp 0.3 ulp 
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The Algorithm 

^ ^1\X\> XBig, set resulr= EXP { t^ - ln(2) ) . 

2 Otherwise, set temp = EXP ( ^Y| ) , and set remit = {temp + Mtemp)l2, 
Notes 

1 ) Umax Is the point at wh ich cosh(^ becomes too large to be represented 
in the floating-point format. 

2) XBig is the point at which e"l^ becomes insignificant compared with e^ 

(In floating-point). 

3) En'ors in the argument are not seriously magnified by this function, 
although the output does become less reliable nearthe ends of the range. 

TANH 
DTANH 

REAL32 FUNCTION TANH (VAL REAL32 X} 
RE:AL€4 function DTANH {VAL R£ALe4 X) 

These compute: tanh(Sl 

Domain: [-Inf, Inf] 

Range: [-1.0, 1.0] 

Primary Domain: [-Log(3)/2, Log(3)/2] = [-0.549. 0.549] 

Exceptions 

None. 
Propagated Error 

A =^cosh2t^, /? = ;!:/sinh g^ cosh(:f) 
Generated Error 

Primary Domain Error MRE RMS 
Single Length: 0.52 ulp 0.2 ulp 

Double Length: 4.6 ufp 2.6 ulp 

The Algorithm 

1 If 1^1 > In(3y2, set temp\- EXP(pq/2). Then set Rwork = 1 - 
2}(^^^t€mp). 

2 Otherwise compute Rwork = tanh(l^) with a floating-point rational 
approximation. 
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3 In both cases, set RESULT = ±/?hotA: according to the sign ofZ. 
Notes 

1) As a floating*point number, tanh(A^ becomes indistinguishable Irom its 
asymptotic values of ±1 .0 for 1^ > HTmax, where HTmax is S.4 for single- 
length, and 19,06 for double-length. Thus the output of TANH is equal to 
±1.0 for such X 

2) This function Is very stable and well-behaved, and en^ors in the argument 
are always diminished by it 

RAN 
DRAH 

REAL32,INT32 FUNCTION RAN (VAL INT32 X) 
REAL64,INT64 FUNCTION DRAN (VAL INT64 X) 

These produce a pseudo-random sequence of integers, and a corre- 
sponding sequence of floating-point numbers between zero and one. 

Domain: integers (see note 1) 

Range: [0.0, 1.0] x Integers 

Exceptions 

None, 

The Algorithm 

1 Produce the next integer in the sequence: JVjt+j = (aN^ + 1 Wf Af 

2 Treat JS^+j as a fixed-point fi'actlon in [0,1), and convert it to floating 
point. 

3 Output the floating point result and the new Integer, 
Notes 

1) This function has two results, the first a reah and the second an integer 
(both 32 bits for single-length, and 64 bits for double-length). The integer 
is used as the argument for the next call to ran, i.e. it 'canies' the pseudo- 
random linear congruential sequence JVt, and it should be kept in scope for 
as long as ran is used. It should be initialized before the first call to RAN 
but not modified thereafter except by the function itself. 

2) If the integer parameter is initialized to the same value, the same 
sequence (both floating-point and integer) will be produced, tf a different 
sequence is required for each run of a program it should be initialized to 
some 'random' value, such as the output of a timer. 
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3) The integer parameter can be copied to another variable or used in 
expressions requiring random integers. The topmost bits are the most 
random. A random integer in the range [0^] can conveniently be produced 
by taking the remainder by (L+1) of the integer parameter shifted right by 
one bit. If the shift Is not done an integer in the range [-L^L] will be 
produced. 

4) The modulusMis23^for single-length and 2^fordouble-length, and the 
multipliers, a, have been chosen so that all M integers will be produced 
before the sequence repeats. However several different integers can 
produce the same floating-point value and so a floating-point output may 
be repealed, although the sequence of such will not be repeated until M 
calls have been made. 

5) The floating-point resu[t is uniformly distributed over the output range, 
and the sequence passes various tests of randomness, such as the 'njn 
test', the 'maximum of 5 test' and the 'spectral test'. 

6) The double-length version is slower to execute, but 'more random' than 
the single-length version. If a highly-random sequence of single-length 
numbers is required, this could be produced by converting the output of 
DRAN to single-length. Conversely if only a relatively crude sequence of 
double-length numbers is required, RAN could be used for higher speed 
and its output converted to double-length. 
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1.5 Host file server library 

Library: hostio . lib 

The host file server libraiy contains routines that are used to communicate with the 
host file server. The routines are independent of the host on which ^e server is 
running. Using routines from this library you can guarantee that programs will be 
portable across all implementations of the toolset. 

Constant and protocol definitions for the hostio library, including error and return 
codes» are provided In the include file hostio . inc. 

The result value from many of the routines in this library can take the value ^ 
spr . operation . failed which is a server dependent failure result. It has been 
left open with the use of s because future server implementations may give more 
information back via this byte. 

1.5.1 Errors and the server run time library 

The hostio routines use functions provided by the host file server. These are 
defined in Appendix C in the Toolset Refemnce Manual. The server is imple- 
mented in C and uses routines in a C run time library, some of which are imple- 
mentation dependent. 

In particular, the hostio routines do not check the validity of stream identifiers, and 
the consequences of specifying an incon^ect streamid may differ from system to 
system. For example, some systems may return an error tag, some may return a 
text message. If you use only those stream kJs returned by the hostio routines that 
open files (so^open, so . open . temp, and so.popen.read), invalid ids are 
unlikely to occur. It is also possible in rare circumstances for a program to fail alto- 
gether with an invalid streamid because of the way the C library is implemented 
on the system. This error can only occur if direct use of the library to perform the 
operation would produce the same en'or. 

1.5.2 Inputting real numbers 

Routines for Inputting real numbers only accept numbers in the standard Occam 
format for REAL numbers. Programs that allow other ways of specifying real 
numbers must convert to the Occam format before presenting them to the library 
procedure. 

For details of Uie occam syntax for real numbers see the Occam 2 Reference 
Manual. 

1.5.3 Procedure descriptions 

In the procedure descriptions, f s is the channel from the host file server, and ts 
is the channel to the host file server. The SP protocol used by the host file server 
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channels is defined in the include file hos tio . inc. The hostio routines are divided 
into six groups: five groups that reflect function and use, and a sixth miscellaneous 
group. The five specific groups are: 

• File access and management 

• General host access 

• Keyboard input 

• Screen output 

• File output 

Each group of routines is described in a separate section. Eadi section begins with 
a list of the routines in the group with their fonnal parameters. This is followed by 
a description of each routine in turn. Note: for those routines which write data to 
a stream (including the screen), if the data is not sent as an entire block then it 
cannot be guaranteed that the data arrives contiguously at Its destination. This is 
because another process writing to the same destination may interleave its server 
requestCs) with those of these routines. 

1.5.4 File access 

This group mcludes routines for managing file streams, for opening and dosing 
files, and for reading and writing blocks of data. 
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Procedure 


Parameter Specifiers 


so . open 


CHAN OF SP fs, ts, VAL []BYT£ name, 
VAL BYTE type, mode, INT32 streamid, 
BYTE result 


so . open . teo^ 


CHAN OF SP fs, ts, VAL BYTE type, 

[so. temp. filename. length] BITE filename, 

INT32 streamid, BYTE result 


so.popen.read 


CHAN OF SP fa, ta, VAL []BYTE filename, 
VAL []BYTE path . variable . name , 
VAL BYTE open. type, INT full.len, 
I] BYTE full. name, 1NT32 streamid, 
BYTE result 


so. close 


CHAN OF SP fs, ta, VAL INT32 streamid, 
BYTE result 


so. read 


CHAN OF SP fs, ts, VAL INT32 streamid, 
INT length, []BYTE data 


so. write 


CHAN OF SP fs, ts, VAL INT32 streamid, 
VAL []BYTE data, INT length 


so . gets 


CHAN OF SP fs, ts, VAL INT32 streamid, 
INT length, I]BYTE data, BYTE result 


so .puts 


CHAN OF SP fs, ts, VAL INT32 streamid, 
VAL []BYTE data, BYTE result 


so. flush 


CHAN OF SP fa, ta, VAL INT32 streamid, 
BYTE result 


so. seek 


CHAN OF SP fa, ts, VAL INT32 strenmid, 
VAL INT32 offset, origin, BYTE result 


so. tell 


CHAN OF SP fs, ts, VAL 1NT32 streamid, 
INT32 position, BYTE result 


so . eof 


CHAN OF SP fs, ts, VAL INT32 streamid, 
BYTE result 


so. f err or 


CHAN OF SP fs, ts, VAL INT32 streamid, 
INT32 error.no, INT length, 
[JBYTE message, BYTE result 


so . remove 


CHAN OF SP fs, ts, VAL [JBYTE name, 
BYTE result 


so . rename 


CHAN OF SP fs, ts, 

VAL [JBYTE oldname, newname, BYTE result 


so. test. exists 


CHAN OF SP fs, ts, 

VAL [JBYTE filename, BOOL exists 
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Procedure definitions 

so . open 

PROC so. open (CHAN OF SP fs^ ts^ 
VAL []BYTE name, 
VAL BYTE type, mode, 
INT32 streamid, BYTE result) 



Opens the file given by name and returns a stream identifier streamidfor 
all future operations on the file until it is closed. If name does not include 
a directory then the file is searched for in the current directory. File type is 
specified by type and the mode of opening by mode. 

type can take the following values: 

£tpt .binary File contains raw bytes only, 

spt.text File contains text records separated by 

newline sequences. 

mode can take the following values: 

spm . input Open existing file for reading, 

spm . output Open new file, or truncate an existing one, 

for writing. 

spm. append Open a new file, or append to an existing 

one, for writing, 
spm. existing. update Open an existing file for update (reading 

and writing), starting at beginning of the file, 
spm. new. update Open new file, or truncate existing one, for 

update, 
spm . append . update Open newfile, or append to an existing one, 

for update. 

result can take the following values: 

spr .ok The open was successful, 

spr. bad. name Null file name supplied, 

spr.bad. type Invalid file type, 

spr. bad. mode Invalid open mode. 

spr, bad. packet. size File name too iarge 

(Le.> sp . max . openname , size) . 

^ spr . operation . failed If result ^ spr, operation . failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference ManuaL) 
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30 . open . tftinp 



PROC so . open . temp 

(CHAN OF SP fSf ts, 
YJO. BYTE type, 

[so. temp. filename. length] BYTE filename, 
INT32 streamid, BYTE result} 

Opens a temporary file in spm . new . update mode. The first filename tried 
is temp 00. If the file already exists the nn suffix on the name temp nn is 
incremented up to a maximum of 9999 until an unused number is found. 
If the number exceeds 2 digits the last character of ten^ is overwritten. For 
example: if the number exceeds 99 the p is ovenwritten, as in tem999; if 
the number exceeds 999, the mis overwritten, as in te 9999. File type can 
be spt . binary or spt . text, as with so . open. The name of the file actu- 
ally opened is returned in filename. The result returned can take any of the 
following values: 

spr . ok The open was successful, 

spr.notok There are already 10,000 temporary 

files, 
spr .bad. type Invalid file type specified, 

a spr, operation, failed If results spr. operation, failed 

then this denotes a server returned 

failure. (See section C.2 in the Toolset 

Reference Manual) 



so.popen.read 



PROC so . popen . read 

(CHAN OF SP tBt ts, 
VAL []BYTE filename, 
VAL []BYTE path. variable. name, 
\M. BYTE open* type, 
IKT full.len, []BYTE full. name, 
INT32 streamid, BYTE result) 

As for so. open, but if the file is not found and the filename does not 
include a directory, the routine uses the directory path string associated 
with the host environment variable, gh/en in path . variable . name, and 
performs a search in each directory in the path in turn. This coresponds 
to the searching rules used by the toolset, using the environment variable 
ISEARCH, see section 3.10.2 In the OQCam 2 Toolset User Guide. 

File type can be spt .binary or spt . text, as with so , open. The mode 
of opening is always spm. input. 

The name of the file opened is returned in full .naine, and the length of 
the file name is returned in full . len. If no file is opened, full . len and 
full . name are undefined, and the result will not be spr . ok. 
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The result returned can take any of the following values: 

spr .ok The open was successful. 

spr. bad. name Null name supplied. 

spr.bad, typ« Invalid file type specified. 

spr. bad. packet. size File name is too large 

(i.e. > sp . max . openname . si ze) or 
pa til . variable . name is too large 
(i.e.> sp. max. getenvname. size). 

spr. buffer. overflow The environment string referenced by 

path . variable . name is longer than 
507 characters. 

^ spr . operation . failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manuaf). 



so. close 



PROC so. close (CHAN OF SP fs, ts^ 
VAL INT32 streamid, 
BYTE result) 



Closes the stream identified by streamid. The resuK returned can take any 
of the following values: 

spr . ok The dose was success^l. 

^ spr . operation . failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manual.) 



.read 



PROC so. read (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT length, [JBYTE data) 



Reads a blodc of bytes from the specified stream up to a maximum given 
by the size of the array data. If length returned is not the same as the 
size of data then the end of the file has been reached or an error has 
occurred. 

Note: so. read reads in multiples of the packet size defined by 
sp. max. readbuffer. size. For greatest efficiency, read requests 
should be made in multiples of this size. 
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so. write 



PROC so.vrite (CHAN OF 5P fs, ta, 
VAL IHT32 streamid, 
VAL [JBYTE data, 
INT length) 

Writes a block of data to the specified stream, ff length is less than the 
size of data then an error has occurred. 

Kote: so. write writes in multiples of the packet size defined by 
flp, max, writ«buffer. size. For greatest efficiency, write requests 
should be made in multiples of this size. 



so . gets 



PROC so. gets (CHAN OF SP £s, ts^ 
VAL INT32 streamid, 
INT length, [JBYTE data, 
BYTE result) 

Reads a line from the specified input stream. Characters are read until a 
newline sequence is found, the end of the file is reached, or 
sp . max . readbuf f er . size characters have been read. The characters 
read are In the first length bytes of data. The newtine sequence is not 
Included in the returned array. If the read fails then either the end of file has 
been reached or an error has occurred. 

The result returned can take any of the following values: 



spr . ok 

spr. bad. pac]cet. size 

spr .buffer . overflow 



The read was successful. 

Data is too large 

(> sp. max. readbuf fer. size). 

The line was larger than the buffer data 
and has been tmncated to fit. 



^ spr. operation, failed If result ^ spr. operation, failed 

then this denotes a server returned 
failure. (See section 0.2 in the Toolset 
RBference Manua!.} 



72 TDS 368 01 



March 1993 



72 



so. puts 



PROC so. puts (CHAN OF SP fa, t», 
VAL INT32 streainid, 
VAL []BYTE data, BYTE result) 

Writes a line to the specified output stream. A newline sequence is added 
to the end of the line. The size of data must be less than or equal to the 
hostio constant sp. max. writebuffer. size. 

The result returned can take any of the following values: 

spr . ofc The write was successful, 

spr .bad , packet . size SIZE data is too large 

( > sp. max. writebuffer. size), 
> spr . operation . failed If result ^ spr . operation . failed 

then this denotes a server returned 

failure. (See section C.2 in the Toolset 

Reference Manual.) 



so . flush 



PROC so. flush (CHAN OF SP fs, ts, 
VAL IHT32 streamid; 
BYTE result) 

Flushes the specified output stream. All internally buffered data is written 
to the stream. Write and put operations that are directed to standard output 
are flushed automatically. The stream remains open. 

The result returned can take any of the following values: 

spr . ok The flush was successful. 

^ spr . operation , failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manual.) 
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so . seek 



PROC so. seek {CHAN OF SP fs, ts, 
VAL INT32 streamid, 
VAL INT32 offset, origin, 
BYTE result} 



Sets the file position for the specified stream. A subsequent read or write 
will access data at the new position. 

For a binary file the new position will be offset bytes from the position 
defined by origin. For a text file offset must be zero or a value returned 
by so, tell, in which case origin must be spo. start. 

origin may take the following values: 

spo . start The start of the file. 

spo. current The oirrent position in the file. 

spo , end The end of the file. 

The result returned can take any of the following values: 

spr . ok The operation was successful. 

spr . bad . origin Invalid origin. 

^ spr . operation . failed If result ^ spr . operation , failed 

then this denotes a server returned 
Allure. (See section C.2 in the Toolset 
Reference Manual.) 



BO . tell 



PROC so. tell (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT32 position, BYTE result) 

Returns the current file position for the specified stream. 

The result returned can take any of the following values: 

spr . ok The operation was successful. 

^ spr * operation , failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure. (See section C.2 In the Toolset 
Refsrence ManuaL) 



so.eof 



PROC so.eof (CHAN OF SP fs, ts, 

VAL INT32 streamid^ BYTE result] 
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Tests whether the specified stream has reached the end of a file. The end 
of file is reached when a read operation attempts to read past the end of 
file. 

The result returned can take any of the following values: 



spr . ok 

>spr . operation . failed 



End of file has been reached. 
If result ^ spr . operation . failed 
then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manual.) This result will also 
be obtained if eo£ has not been reached. 



so. f error 



PROC so. f error (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
INT32 error.no, INT length, 
[]fiYT£ message, BYTE result) 

Indicates whether an error has occurred on the specified stream. The 
integer error . no is a host defined error number. The returned message 
Is in the first length bytes of message, length will be zero if no message 
can be provided. If the returned message is longer than 503 bytes then it 
is truncated to this size. 

The result returned can take any of the following values: 



spr. buffer .overflow 



spr.ofc An error has occurred on the specified 

stream. 

An error has occun'ed but the message is 
too large formessage and has been trun- 
cated to frt. 

^ spr . operation . f ai led If result ^ spr , operation . failed 

then this denotes a sen/er returned 
failure. {See section C.2 in the Toolset 
Reference Manual.) This result will also 
be obtained if no error has occurred on 
the specified stream. 



so . remove 



PROC so, remove tCHflN OF SP fs, ts, 

VAL I] BYTE name, BYTE result) 

Deletes the specified file. 

The result returned can take any of the following values: 
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spr . ok The delete was successfuL 

apr. bad. name Null name supplied. 

spr. bad. packet. size SIZE name is too large 

( > sp. max. removename. size). 

S spr . operation . failed If result i spr . operation . failed 

then this denotes a server returned 
feilure. (See section C.2 in the Toolset 
Reference Manual.) 

so . rename 

PROC »o. rename (CHAN OF SP fa, tm, 

VAL []BYTE oldname, nevname, 
BYTE result) 

Renames the specified file. 

The result returned can take any of the foilowing values: 

spr. ok The operation was successHil. 

spr , bad. name Null name supplied. 

spr. bad. packet, size File names are too large 

((SIZE oldname ^ SIZE newnsuae) 
> sp . max . renamename . size). 

fe spr . operation . failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure, (See section C.2 in the Toolset 
Reference Manual.) 

so. test. exists 

PROC so. test. exists (CHAN OF SF fs, ts, 

VAL [JBYTE filename, 
BOOL exists) 



Tests if the specified file exists. The value of exists is TRUE if the file 
exists, otherwise it is FALSE. 
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1.5,5 General host access 



This group contains routines to access the host computer for system information 
and services. 



Procedure 


Parameter Specifiers 


so . commandline 


CH&N OF SP fs, ts, 
VU BYTE all, INT length, 
[]BYTE string, BYTE result 


s o . parse . command , line 


CHAN OF SP fs, ta, 

VAL [] []BYTE option. strings r 

VAL [IINT 

option. parameters . required^ 

[]BOOL option. exists, 

[] 12] INT option. parameters, 

INT error. len, []BYTE line 


so.getenv 


CHAN OF SP fs, ts, 
VAL []BYT£ name, INT length, 
[ I BYTE value, BYTE result 


so. system 


CHAN OF SP fs, ts, 
VAL []BYTE command, 
INT32 status, BYTE result 


so. exit 


CHAN OF SP fs, ts, 
VAL INT32 status 


50 , core 


CHAN OF SP fs, ta 

VAL INT32 offset, 

INT bytes. read, 

[]BYTE data, BYTE result 


so. version 


CHAN OF SP fs, ts, 

BYTE version, host, os, board 



Procedure definitions 

so . commandline 

PROG so. commandline (CHAN OF SF fs, ts, 

VAL BYTE all, INT length, 
[]BYTE string, BYTE result) 

Returns the command line passed to the server when it was involved. If all 
has the value sp . short . commandline then all valid server options and 
their arguments are stripped from the command line, as is the server 
command name. If all is sp. whole, commandline then the command 
line is returned exactly as it was invoked. The returned command line is in 
the first length bytes of string. If the command line string is longerthan 
507 bytes then it is truncated to this size. The result returned can take any 
of the following values: 
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spr.ok The Operation was successful. 

spr, buffer, overflow Command line too long for string and 

has been truncated to fit. 

;£ spr . operation . failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manual.) 

so .parse . coiomand . line 

PROC so.parse. command. line 

{CHAN OF SP fs, ts, 
VAL [] []BYT£ option. strings, 
VAL []INT option. parameters. required, 

[]BOOL option. exists, 

[ ] [ 2 ] INT option . parameters , 
INT error. len, []BYTE line) 

This procedure reads the server command line and parses it for specified 
options and associated parameters. 

The parameter option . strings contains a list of all the possible options 
and must be in upper case. Options may be any length up to 256 bytes and 
when entered on the command line may be either upper or lower case. 
Because all of the strings in option, st:rings must be the same length, 
trailing spaces should be used to pad. 

To read a parameter that has no preceding option (such as a file name) then 
the first option string should be empty (contain only spaces). For example, 
consider a program to be supplied with a file name, and any of three options 
W, 'B' and 'C. The an^y option . strings would look like this: 

YAL option. strings IS ['' ", "A", "B", "C] : 

The parameter option. parameters .required indicates if the con'e- 
sponding option (in option . strings) requires a parameter. The values 
it may take are: 

spopt . never Never takes a parameter 

spopt . maybe Optionally takes a parameter, 

spopt. always Must take a parameter 

Continuing the above example, if the file name must be supplied and none 
of the options take parameters, except for 'C, whk;h may or may not have 
a parameter, then option . parameters . required would look like this: 

VAL option. parameters. required IS 
[ spopt , always , spopt . never , 
spopt. never, spopt. maybe] : 
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If an option was present on the command line the con'esponding element 
of option . exists is set to TRUE, Otherwise it is set to FALSE, 

If an option was followed by a parameter then the position in the array line 
where the parameter starts and the length of the parameter are given by 
the first and second elements respectively in the corresponding element 
in option. parameters. 

If an error occurs whilst the command line is being parsed then error . len 
will be greater than zero and line will contain an error message of the 
given length. If no en^or occurs then line will contain the command line as 
supplied by the host file server. 

Most of the possible en'or messages are self-explanatory, however, it is 
worth noting the meaning ofthe error 'Command line error; called incor- 
rectly'. 

This en^or means that either: 

• option. strings was null, or 

• SIZE option. exists, SIZE option . parameters or 
SIZE option, parameters, required does not equal 
SIZE option . strings. 



so.getenv 



PROC so.getenv (CHAN OF SP fs, ts, 
VAL []BYTE name^ 
INT length, []BYTE value, 
BYTE result) 

Returns the string defined for the host environment variable name. The 
returned string is in the first length bytes of value. If name Is not defined 
on the system result takes the value > spr . operation . failed. If the 
environment variable's string is longer than 507 bytes then it is truncated 
to this size. 

The result returned can take any ofthe following values: 

spr. ok The operation was successful, 

spr. bad. name The specified name is a null string, 

spr. bad. packet, size SIZE name IS tOO large 

( > sp.max.getenvname.size). 

spr .buffer .overflow Environment string too large for value but 

has been truncated to fit. 

^ spr. operation. failed If results spr. operation, failed 

then this denotes a server retumed 
failure. (See section C.2 in the Toolset 
Reference ManuaL) 
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so. system 

PROC so. system {CHAN OF SP fs, ts, 
VAL []BYTE command, 
INT32 status, BYTE result) 

Passes the string command lo the host command processor for execution. 
If the command string is of zero Jength result takes the value spr . ok if 
there is a host command processor, othenvise an error is relumed. 

If coimnand is non-zero in length then states contains the host-speciHed 
value of the command, otherwise it is undefined. 

The result retumed can take any of the following values: 

spr , ok Host command processor exists, 

spr. bad. packet. size The array command is too large 

(> sp. max. systemcommand, size). 

a spr . operation . failed If result £ spr . operation . failed 

then this denotes a server retumed 
failure. (See section 02 in the 7oo/sef 
RefefBnce Manuai) 



so. exit 



PROC so. exit (CHAN OF SP fs, ts, 
VAL INT32 status) 

Terminates the server, which returns the value of status to its caller. If 
status has the special value sps . success then the server will terminate 
with a host specific 'success' result. If status has the special value 
sps. failure then the server will terminate with a host specific failure' 
result. 



so, core 



PROC so. core (CHAN OF SP fs, tSr 

VAL INT32 offset, INT bytes. read, 
I ] BYTE data, BYTE result) 

Returns the contente of the root transputer's memory as peeked from the 
transputer when iserver is invoked with the analyze ('SA') option. The 
start of the memory segment is given by offset which is an offset from 
the base of memory (and is therefore positive). The number of bytes to be 
read is given by the size of the data vector. The number of bytes actuary 
read into data is given by bytes . read. An error is returned if offset is 
larger than the total amount of peeked memory. 

The result retumed can take any of the following values: 
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spr.ok The operation was successful. 

spr. bad. paclcet .size The array data is too large 

{> sp.max.corerequeat.size). 
a spr, operation. failed If results spr. operation, failed 

then this denotes a server returned 

failure. (See section C.2 in the Toolset 

Reference Manual.) 

This procedure can also be used to determine whether the memory was 
peeked {whetherthe serverwas invoked vwth the 'SX option), by spedfying 
a size of zero for data and offset. If the result returned is spr.ok the 
memory was peeked. 



so. version 



PROC so. version (CHAN OF SP fs, ts, 

BYTE version, host, os, board) 

Returns version information about the server and the host on which it Is 
mnning. A value of zero for any of the items indicates that the infomiation 
is unavailable. 

The version of the server is given by version. The value should be divided 
by ten to yield the true version number. For example, a value of 15 means 
version 1.5, 

The host machine type is given by host, and can take any of the following 
values: 



sph . unknown unknown host type 

sph.PC IBM PC 

sph-S370 IBM 370 Architecture 

sph.NECPC NEC PC 

sph. VAX DEC VAX 

sph. SUN3 Sun Microsystems Sun 3 

sph. BOX. SUN4 Sun Microsystems Sun 4 

sph.BOX.SUN386 Sun Microsystems Sun 386i 

sph . BOX . APOLLO Apollo 

sph , BOX , ATARI Atari ST or TT 

Values up to 127 are reserved for use by INMOS. 

The host operating system is given by os, and can take any of the following 
values: 
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spo . iinknown 
spo.DOS 
spo . HELIOS 

spo. VMS 
spo . SUNOS 
spo. CMS 
spo^TOS 



unknown OS type 

DOS 

HELIOS 

VMS 

SunOS 

CMS 

TOS 



Values up to 127 are reserved for use by INMOS. 

The interface board type is given by board, and can take any of the 
following values; 



spb.unknomi 

spb.B004 

spb.BOOS 

spb.BOlO 

spb.BOll 

ffpb.B014 

spb.BOlS 

spb.B016 

spb.DRXll 

spb . IBMCAT 

spb.QTO 

spb.UDPLINK 

spb.TCPLiNK 

spb.ACSIUl 



unloiowi board type 

IMS B004 

IMS B008 

IMSB010 

IMSB011 

IMS B014 

IMS 801 5 

IMS B016 

DRX-II 

CAT 

Caplin QTO 

UDP link 

TCP link 

ACSIUV 



Values up to 127 are reserved for use by INMOS. 
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1.5.6 Keyboard input 



Procedure 


Parameter Specifiers 


so.pollkey 


CHAN OF SF fs, ts, 
BYTiC key, result 


so . getkey 


CHAN OF SP fa, ts, 
BYTE key, result 


so. read. line 


CHAN OF SP fs, t»; 
INT len, [IBYTE line, 
BYTE result 


so . read . echo . line 


CHAN OF SP fa, ts, 
INT len, []BYTE line, 
BYTE result 


so . ask 


CHAN OF SP fa, ts, 

VAL []BYTE prompt, replies, 

VAL BOOL display. possible, replies, 

VAL BOOL echo. reply, 

INT reply * n\anber 


so . read . echo . int 


CHAN OF SP fs, ts, INT n, 
BOOL error 


so . read . echo . int32 


CHAN OF SP fs, ts, INT32 n, 
BOOL error 


so . read . echo . int 64 


CHAN OF SP fs, ts, INT64 n, 
BOOL error 


so . read . echo . hex . int 


CHAN OF SP fs, ts, INT n, 
BOOL error 


so . read . echo . hex . int32 


CHAN OF SP fa, ts, INT32 n, 
BOOL error 


so . read . echo . hex . int64 


CHAN OF SP ffl, ts, INT64 n, 
BOOL error 


so . read . echo , any . int 


CHAN OF SP fa, ts, INT n, 
BOOL error 


so . read . echo , real32 


CHAN OF SP fs, ts, REAL32 n, 
BOOL error 


s o , read . echo , real 64 


CHAN OF SP fs, ts, REAL64 n, 
BOOL error 
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Procedure definitions 

so.pollkey 

FROC so.pollkey (CHAN OF SP fs, ts, 
BYTE key, result) 

Reads a single character from the keyboard. If no key is available then it 
returns immediately with > apr, operation. failed. The key is not 
echoed on the screen. 

The result returned can take any of the following values: 

spr.ok A key was available and has been 

returned in key. 
^spr. operation. failed If results spr. operation. failed 

then this denotes a server returned 

failure. (See section C.2 in the Toolset 

Reference Manual.) 

scgetJcey 

PROG so.getkey (CHAN OF SP fs, ts, 
BYTE key, result) 

As so.pollkey but waits for a key if none is available. 

so. read. line 

PROC so. read. line {CHAN OF SP fs, ts, INT len, 
[]BYTE line, BYTE result) 

Reads a line of text from the keyboard, without echoing it on the screen. 
The characters read are in the first len bytes of line. The line is read until 
'RETURN' is pressed at the keyboard. The line is truncated if line is not 
large enough. A newline or carriage retum is not included in line. 

The result returned can take any of the following values: 

spr . ok The read was successful. 

^spr. operation, failed If results spr. operation, failed 

then this denotes a server returned 
failure. {See section C.2 in the Toolset 
Reference Manual.) 
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so . read . echo . line 

FROC so. read. echo. line (CHAN OF SP fs, ts, 

INT len, [IBYTE line, 
BYTE result) 

As so. read. line, but user input (except newline or carriage return) is 
echoed on the screen. 

so. ask 

PBOC so. ask (CHAN OF SP fs, ts, 

VAL []BYTE pron^t, replies^ 

VAL BOOL display. possible, replies f 

VAL BOOL echo.reply^ 

INT reply. number) 

Prompts on the screen for a user response on the keyboard. The prompt 
is specified by the string pron^t, and the list of permitted relies by the 
string replies. Only single character responses are permitted, and 
alphabetic characters are not case sensitive. For example if the permitted 
responses are *¥', 'N' and 'Q' then the replies string would contain the 
characters 'YNQ', and 'y'. 'n' and 'q' would also be accepted, 
reply. number indicates which response was typed, numbered from 
zero. ' ? ' is automatically output at the end of the prompt. 

If display. possible. replies is TRUE the permitted replies are 
displayed on the screen. If echo. reply is TRUE the user*s response is 
displayed. 

The procedure will not return until a valid response has been typed. 

so . read . echo . int 

PROC so. read. echo. int (CHAN OF SP fs, ts, INT n, 

BOOL error) 

Reads a decimal integer typed at the keyboard and displays it on the 
saeen. The number must be terminated by 'RETURN', The boolean 
error is set to TRUE if an invalid integer is typed, false otherwise. 

so . read . echo . int32 

PROC so. read. echo. int32 (CHAN OF SP fs, ts, 

INT32 n, BOOL error) 

As so. read. echo, int but reads 32-bit numbers. 
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so . read , eciho . int 64 

PROC so. read. echo. int64 {CHAN OF SP fs, ts, 

INT64 n, BOOL error) 

As so. read. echo. int but reads &4-btt numbers. 

so . read . echo . hex . int 

PROC so. read. echo. hex. int (CHAN OF SP fs; ts^ 

INT n, BOOL error) 

As so . read . echo . int but reads a number in hexadecimal format. The 
number may be in lower or upper case but must be prefixed with either '#', 
or '$■ which directly indicates a hexadecimal number, or*%', which means 
add MOSTNEG INT to the given hex (using modulo arithmetic). For 
example, on a 32-bit transputer %70 Is interpreted as #80000070, and on 
a 16-bit transputer as #8070. This is useftil when specifying transputer 
addresses, which are signed and start atMOSTNEG int. 

s o . read , echo . hex . int32 

PROC so. read. echo. hex. int32 (CHAN OF SP fs, ts, 

INT32 n, BOOL error) 

As so . read . echo , hex , int but reads 32-bit numbers. 

so P read, echo .hex . int64 

PROC so. read. echo. hex. int64 (CHAN OF SP fs, ts, 

INT64 n, BOOL error) 

As SO , read . echo . hex . int but reads 64-blt num bers. 

so , read . echo . any . int 

PROC so. read. echo. any, int (CHAN OF SP fs, ts, 

INT n, BOOL error) 

As so . read . echo , int but accepts numbers in either decimal or hexa- 
decimal format. Hexadecimal numbers may be lower or upper case but 
must be prefixed with either '#' or '$' which specifies the number directly, 
or '%\ which means add mostneg int to the given hex (using modulo 
arithmetic). For example, on a 32-bit transputer %70 is interpreted as 
#80000070, and on a 16-bit transputer as #8070. This is useful when 
specifying transputer addresses, which are signed and start at mostneg 
INT. 
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so . read , echo . real32 

FROC so. read. echo. real32 (CHAN OF SP £s, t&, 

REAL32 n, BOOL error) 

Reads a real number typed at the keyboard and displays it on the screen. 
The number must confomi to occam syntax and be terminated by 
■RETURN'. The boolean variable error is set to TRUE if an invalid number 
is typed, FALSE otherwise, 

so . read . echo . real64 

PROC so. read. echo, real€4 (CHAN OF SP fs, ts, 

R£AL64 n, BOOL error) 

As so. read. echo. re3l32 but for 64-bjt real numbers. 



1 .5 J Screen output 



Procedure 


Parameter Specifiers 


so, write. char 


CHAN OF SP fs, ts, 
VAL BYTE char 


5o.vrite.nl 


CHAN OF SP fs, ts, 


so . write . string 


CHAN OF SP fs, ts, 
VAL []BYTE string 


so.write.string.nl 


CHAN OF SP fs, ts, 
VAL []BYTE string 


so.write.int 


CHAN OF SP fs, ts, 
VAL INT n, width 


30.write.int32 


CHAN OF SP fs, ts, 

VAL INT32 n, VAL INT width 


so . write . int64 


CHAN OF SP fs, ts, 

VAL INT 64 n, VAL INT width 


so . write . hex . int 


CHAN OF SP fs, ts, 
VAL INT n, width 


so. write. hex. int32 


CHAN OF SP fs, ts, 

VAL INT32 n, VAL INT width 


so . write .hex . int 64 


CHAN OF SP fs, ts, 

VAL INT64 n, VAL INT width 


so.write.real32 


CHAN OF SP fs, ts, 

VAL REAL32 r, VAL INT Ip, Dp 


so. write. real. 64 


CHAN OF SP fs, ts, 

VAL REAL64 r, VAL INT Ip, Dp 
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Procedure definitions 

so. write, char 

FROC so. write. char (CHAN OF SF fa^ ts, 
VAL BYTE char) 

Writes the single byte char to the screen. 
so.write.nl 

PROC so.write.nl (CHAN OF SP fs, ts) 

Writes a newline sequence to the screen. 

so . write . string 

PROC so. write. string (CHAN OF SP fs, ts, 

VAL []BYTE string) 

Writes the string string to the screen. 

50 . write . string . nl 

PROC so.write.string.nl (CHAN OF SP fs, ts, 

VAL []BYTE string) 

As so . write . string, but appends a newline sequence to the end of the 
string. 

so. write. int 

PROC so. write. int (CHAN OF SP fs, ts, 
VAL INT n, width) 

Writes the value n (of type INT) to the screen as decimal ASCli digits, 
padded out with leading spaces and an optional sign to the specified field 
width, width- If the field widtti is too small for the number it is widened as 
necessary; a zero value for width specifies minimum width. A negative 
value for width is an error. 

so. write. int32 

PROC so. write. in t32 {CHAN OF SP fs, ts, 

VAL INT32 n, VAL INT width) 

As so , write . int but for 32-bit integers. 

so.write.int64 

PROC so.write.int64 (CHAN OF SP fs, ts, 

VAL INT64 n, VAL INT width) 

As so. write, int but for 64-bit integers. 
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so. write. hex. int 



PROC so. write. hex. int {CHAN OF SP f», ts, 

VAL IKT n, width) 



Writes the value n (of type ikt) to the screen as hexadecimal ASCII digits, 
preceded by the '#' character. The number of characters printed is width 
+ 1, If width is larger than the size of the number then the number is 
padded with leading 'O's or 'F's as appropriate. If width is smaller than the 
size of the number, the number is truncated, from the left, to width digits. 
A negative value for width is an error. 

so , write . hex . int32 

PROC so. write. hex. int 64 (CHAN OF SP fs, ts, 

YAL INT32 n, 
VAL INT width) 

As so . write . hex . int but for 32-bit Integers, 

so . write .hex . int64 

PROC so. write. hex, int64 {CHAN OF SP fs, ts, 

VAL INT64 n, 
VAL INT width) 

As so. write. hex. int but for 64-bit integers. 

so . write . reaI32 

PROC so.write.real32 (CHAN OF SP £s, ts, 

VAL REAL32 r, 
VAL INT Ip, Dp) 

Writes the value r (of type REAL32) to the screen as ASCII characters 
formatted using Ip and Dp as described under REAI.32T0STRING (see 
section 18). 

Note: Due to fixed size intemal buffers, this procedure will be invalid if the 
string representing the real number is longer than 24 characters. If this is 
a problem, it is suggested you write your own procedure to perfomi this 
function. The procedure should include a buffer set to the required size, a 
call to REAL32T0STRING, followed by a cali to so. write. 

so . write . real €4 

PROC so. write. real64 (CHAN OF SP fs, ts, 

VAL REAL64 r, 
VAL INT Ip, Dp) 
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As so .write . real32 but for 64-bit real numbers. The formatting vari- 
ables Ip and Dp are described underREALS^TOSTRiNG (see section 1 .8). 

Note : Due to fixed size internal buffers, this procedure will be invalid if the 
string representing the real number is longer than 30 characters. If this is 
a problem, it is suggested you write your own procedure to perform this 
function. The procedure should include a buffer set to the required size, a 
call to REflL64TOSTRiNG, followed by a call to so .write. 

1.5.8 File output 

These routines write characters and strings to a spedfied stream, usually a file. 
The result returned can take the values spr . ofc, spr . notok or, very rarely, > 
spr . operation , failed. 



Procedure 


Parameter Specifiers 


so , f write . char 


CHAN OF SP fa, ts, 

VAL INT32 streamid, 

VAL BYTE char, BYTE result 


so.fwrite.nl 


CHAN OF SP fa, ts, 

VAL INT32 streamid, BYTE result 


so . f write . string 


CHAN OF SP fSr ts, 

VAL INT32 streamid, 

VAL []BYTE string, BYTE result 


so . f write . string . nl 


CHAN OF SP fs, ts, 
VAL INT32 streamid, 
VAL []BYTE string, 
BYTE result 


so. f write. int 


CHAN OF SP fs, ts, 

VAL INT32 streamid, 

VAL INT n, width, BYTE result 


so . f write . int32 


THflN OF SP fs, ts, 
VAL INT32 streamid^ n, 
VAL INT width, 
BYTE result 


so . fwrite . int64 


CHAN OF SP fa, ts, 

VAL INT32 streamid, 

VAL INT64 nr VAL INT width, 

BYTE result 


so . fwrite . hex . int 


CHAN OF SP fs, ts, 

VAL INT32 streamid, 

VAL INT n, width, BYTE result 


so . fwrite . hex . int32 


CHAN OF SP fa, ts, 

VAL INT 32 streamid, n 

VAL INT width, BYTE result 
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Procedure 


Parameter Specifiers 


so . f write . hex . int64 


CHAN OF SP fs, ts, 




VAL INT32 streamid, 




VAL INT64 n^ VAL INT width, 




BYTE result 


so . f write . real32 


CHAN OF SP fs, ts, 




VAL INT32 streamid, 




VAL REAL32 r, VAL INT Ip, Dp, 




BYTE result 


so . fvrite , 3:eal64 


CHAN OF SP fs, t». 




VAL INT32 streamidr 




VAL REAL64 r, VAL INT Ip, Dp, 




BYTE result 



Procedure definitions 

so . fwrite . char 

PROC so, fwrite. char (CHAN OF SP fs, ts, 
VAL INT32 streandd, 
VAL BYTE char, 
BYTE result) 

Writes a single character to the specified stream. The result spr.notok 
will be returned if the character is not written. 

so.fwrite.nl 

PROC ao.fwrite.nl (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
BYTE result} 

Writes a newline sequence to the specified stream. 

If result t3l<es a value > spr . operation . failed then this denotes a 
server returned failure, details of which are documented in in section C.2 
of the Toolset Reference Manual. 

so . fwrite . string 

PROC so. fwrite, string {CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL []BYTE string, 
BYTE result) 

Writes a string to the spedfied stream. The result spr,notok will be 
returned if not all the characters are written. 

so . fwrite . string.nl 

PROC so. fwrite, string.nl (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL [IBYTE string, 
BYTE result) 
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As so. fwrite- string, but appends a newline sequence to the end of 
the string. 

The result returned can take any of the following values: 

spr , oh The operation was successful. 

spr , no tok Not all of the characters were written . 

^ spr . operation . failed If result ^ spr . operation . failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference ManuaL) 

so. f write. int 

PROC so. f write. int (CHAN OF SP fs, ts, 
VAL INT32 streamid, 
VAL INT n, width, 
BYTE result) 

Writes the value n (of type INT) to the specified stream as decimal ASCII 
digits, padded out with leading spaces and an optional sign to the specified 
field width, width. If the field width is too small for the number it is widened 
as necessary; a zero value for width specifies minimum width. A negative 
value for width is an error 

The result spr . notok wll be returned if not all of the digits are written. 

so . f write . int32 

PROC so. f write. int32 {CHftN OF SP fs, ts, 

YAL INT32 atreamid, n, 
VAL INT width, 
BYTE result) 

As so . fwrite . int but for 32-bit integers, 

so . fwrite . int64 

PRCX: so. fwrite. int64 {CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT64 n, VAL INT width, 
BYTE result) 

As so . fwrite . int but for 64-bJt integers. 

so . fwrite . hex . int 

PROC so, fwrite, hex. int (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL INT n, width, 
BYTE result) 
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Writes the value n (of type INT) to the specified stream as hexadecimal 
ASCII digits preceded by the '#' character The number of characters 
printediswidth + i, Ifwidthislargerthan the size of the number then 
the number is padded with leading 'O's or 'F's as appropriate. If width is 
smaller than the size of the number, then the number is tmncated, from the 
left, to width digits. A negative value for width is an en'or. 

The result spr , notok will be returned if not all the characters are written. 

so . fwrite . hex . int32 

PROC so. fwrite. hex. int32 (CHAN OF SP fS; ts, 

VAL INT32 atreamid, n 
VAL INT width, 
BYTE result) 

As so . fwrite . hex . int but for 32-bit integers. 

so . fwrite . hex . int64 

PROC so. fwrite, hex. int64 (CHAN OF SP fa, ts, 

VAL INT32 streamidr 
VAL INTe4 n, 
VAL INT width, 
BYTE result) 

As so . fwrite . hex . int but for 64-bit integers. 

so . fwrite . real32 

PROC so, f write, real32 (CHAN OF SP fs, ts, 

VAL INT32 streamidf 
VAL REAL32 r, 
VAL INT Ip, Dp, 
BYTE result) 

Writes the value r (of type REAL32) to the specified stream as ASCII char- 
acters formatted using Ip and Dp as described under R£AL32T0STRING 
(see section 1 .8). 

The result spr . notok wil[ be returned If not all the characters are written. 

Note: Due to fixed size internal buffers, this procedure will be invalid if the 
string representing the real number is longer than 24 characters. If this is 
a problem, it is suggested you write your own pnacedure to perform this 
function. The procedure should include a buffer set to the required size, a 

call to REAL32TOSTRING, followed by a call to so.%n:ite. 

so . fwrite . real64 

PROC so. fwrite. real 64 (CHAN OF SP fs, ts, 

VAL INT32 streamid, 
VAL REAL64 r, 
VAL INT Ip, Dp, 
DYT£ result) 
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As so . fwrite. real32 but for 64-bit real numbers. The formatting vari- 
ables Ip and Dp are described under real32T0String (see section 18). 

Note : Due to fixed size internal buffers, this procedure will be invafid if the 
string representing the real Humberts longer than 30 characters. If this is 
a problem, it is suggested you write your own procedure to perform this 
function. The procedure should include a buffer set to the required size, a 
call to REAL64TOSTRING, followed by a call to so. write. 

1.5.9 Miscellaneous 

This miscellaneous group includes procedures for 

• Time and date processing 

• Buffering and multiplexing 
Time processing 



Procedure 


Parameter Specifiers 


so . time 


CHAN OF SP tSf ts, 
INT32 localtime, UTCtime 


so . time . to . date 


VAL INT32 input. time, 
[so.date,lenIIKT date 


so.date.to.ascii 


VAL [ao-date.len]INT date, 

VAL BOOL long. years, 

VAL BOOL days. first, 

[so. time. string. len] BYTE string 


so . time . to , ascii 


VAL INT32 time, 
VAL BOOL long. years, 
VAL BOOL days, first 
[so. time. string. len] BYTE string 


so . today , date 


CHAN OF SP fs, ts, 
[so. date. len] INT date 


so . today . ascii 


CHAN OF SP fs, ts, 
VAL BOOL long. years, 
VAL BOOL days. first, 
[so. time. string. len] BYTE string 



so . time 



PROC so. time (CHAN OF SP fs, ts, 

INT32 localtime, UTCtime) 

Returns the local time and Coordinated Universal Time. Both times are 
expressed as the number of seconds that have elapsed since midnight on 
1st January, 1970. If UTC time is unavailable then it will have a value of 
zero. The times are given as unsigned iNT32s. 



72 TDS 368 01 



March 1993 



94 



so. time. to, date 

PROC SO . time . to . date (VAL INT32 input. time , 

[so,date.len]INT date) 

Converts time {as supplied by so , time) to six integers, stored in the date 
array. The elements of the array are as follows: 



Element of array 


Data 





Seconds past the minute 


1 


Minutes past the hour 


2 


The hour (24 hour dock) 


3 


The day of the month 


4 


The month (1 to 12) 


5 


The year (4 digits) 



so . date . to . ascii 

R%OC so. date. to, ascii 

(VAL [so. date, len] INT date, 
VAL BOOL long. years, 
VAL BOOL days. first, 
[so. time. string.len] BYTE string) 

Converts an an'ay of six integers containing the date (as supplied by 
so . time . to . date) into an ASCII String Of the form: 

HH:MM:SS DD/MM/YYYY 

If long. years is FALSE then year is reduced to two characters, and the 
last two characters of the year ^eld are padded with spaces, [f 
days . first is FALSE then the ordering of day and month Is changed (to 
the U.S. standard). 

so . time . to . ascii 

PROC so. time. to. ascii 

(VAL INT32 time, 
VAL BOOL long. years, 
VAL BOOL days. first 
[ so. time. string.len] BYTE string) 

Converts time (as supplied by so . time) into an ASCII string, as described 
for so . date . to . ascii. 

so . today . date 

FROC so. today. date (CHAN OF SP fs, ts, 

[so. date. len] INT date) 
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Gives today's date, in local time, as six integers, stored in the an'ay date. 
The format of the array is the same as for so . time . to . date. If the date 
is unavailable all elements in date are set to zero. 



so. today, ascii 

PROC so. today, ascii 

(CHAN OF SP fs, ts, 
VMi BOOL long. years, days. first, 
[so. time. string. len] BYTE string) 

Gives today's date, in local time, as an ASCII string, in the same format as 
procedure so .date . to.ascii. If the date is unavailable string is filled 
with spaces. 

Buffers and multiplexors 

This group of procedures are designed to assist with buffering and multiplexing 
data exchange between the program and host. 



Procedure 


Parameter Specifiers 


so, buffer 


CHAN OF SP fs, ts, 
from . user , to . user , 
CHAN OF BOOL stopper 


so , overlapped, buff er 


CHAN OF SP fs, ts, 
from . user, to . user , 
CHAN OF BOOL stopper 


so. multiplexor 


CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, 
to. user, 
CHAN OF BOOL stopper 


so . overlapped . mul tiplexor 


CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, 
to. user, 

CHAN OF BOOL stopper 
[]INT queue 


so.pri .multiplexor 


CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, 
to. user, 
CHAN OF BOOL stopper 


so . overlapped . pri . multiplexor 


CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, 
t:o.user, 

CHAN OF BOOL stopper 
[]INT queue 
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Buffering procedures 

so. buffer 

PROC 30, buffer (CHAN OF SP fs, ts, 

from . user , to . user , 
CHAN OF BOOL stopper) 

This procedure buffers data between the user and the host. It can be used 
by processes on a network to pass data to the host across intervening 
processes. It is terminated by sending either a TRUE orFALSE value on the 
channel stopper. 

so . overlapped .buff er 

PROC so. over lapped. buffer {CHAN OF SP f s ^ ts, 

from . user , 
to . user ; 
CHAN OF BOOL stopper) 

Similar to so. buffer, but allows many host communications to occur 
simultaneously through a train of processes. This can improve efficiency 
if the communications pass through many processes before reaching the 
server It is terminated by either a TRUE or FALSE value on the channel 
stopper. 

Multiplexing procedures 

Note: when pairs of channels are passed as parameters, they are normally passed 
as input then output Menceallso. ...routines take the first parameters fs, ts(Le. 
from sen/er, to sen^e;). The multiplexors take the next two parameters as from user, 
to user which will normaliy correspond with to server, from sen/er 

so. multiplexor 

PROC so. multiplexor (CHAN OF SP fs^ ts, 

[]CHAN OF SP from. user, 

to . user f 
CHAN OF BOOL stopper) 

This procedure multiplexes any number of pairs of SP protocol channels 
onto a single pair of SP protocol channels, which may go to the file server 
or another SP protocol multiplexor {or buffer). It is terminated by sending 
either a true or false value on the channel stopper. For n channels, 
each channel is guaranteed to be able to pass on a message for every n 
messages that pass through the multiplexor. This is achieved by cycling the 
selection priorityfrom the lowest index of from. user. However, stopper 
always has highest priority. 
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so . overlapped .multiplexor 

PROC so. overlapped. multiplexor 

{CHAN OF SP fSf ts, 
nCHAN OF SP from, user, to. user , 
CHAN OF BOOL stopper, 
[jINT queue) 

Similar to so. multiplexor, but can pipeline server requests. The 
number of requests than can be pipelined is determined by the size of 
queue, which must provide one word for each request that can be pipe- 
lined. If SIZE queue is zero then the routine simply waits for input from 
stopper. Pipelining improves efficiency if the server requests have to 
pass through many processes on the way to and from the server. It is termi- 
nated by sending either a TRUE or FALSE value on the channel stopper. 

The multiplexing is done in the same cyclic manner as in 

so .multiplexor, stopper has higherpriority than any Of from. user. 

so. pri. multiplexor 

PROC so, pri. multiplexor 

(CHAN OF SP fs, ts, 
[]CHAN OF SP from, user, to. user, 
CHAN OF BOOL stopper) 

As so .multiplexor but the multiplexing is not done in a cyclic manner; 
rather there is a hierarchy of priorities amongst the channels - 
from. user: from.user[i] is of higher priority than from.user[j] , 
for i < j. Also stopper isof lower priority than any of from. user. 

so. overlapped. pri .multiplexor 

PROC so. overlapped. pri. multiplexor 
(CHAN OF SP fs, ts, 
[]CHAN OF SP from. user, to. user, 
CHAN OF BOOL stopper, 
[] INT queue) 



As so. overlapped. multiplexor but the multiplexing is done in the 
same prioritized manner as In so. pri. multiplexor, stopper has 
higher priority than any of from. user. 
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1.6 Streamio library 

Library: streamio. lib 

The streamio library contains routmes for reading and writing to files and to the 
tenminal at a higher level of abstraction than the hostio library. The file strea- 
mio. inc defines the KS and SS protocols and constants used by the streamio 
library routines. The result value from many of the routines in this library can take 
a value > spr . operation . failed which is a server dependent failure result. It 
has been left open with the use of > because future server implementations may 
give more failure information back via this byte. Names for result values can be 
found in the file hostio . inc. 

The streamio routines can be dassiHed into three main groups: 

• Stream processes 

• Stream input procedures 

• Stream output procedures. 

Stream input and output procedures are used to input and output characters in 
keystream KS and screen stream SS protocols. KS and SS protocols must be 
converted to the server protocol before communicating with the host. 

Stream processes convert streams from keyboard or screen protocol to the server 
protocol SP or to related data structures. They are used to transfer data from the 
stream input and output nautines to the host. Stream pH-ocesses can be run as 
parallel processes serving sb-eam input and output routines called in sequential 
code. For example, the following code clears the screen of a terminal supporting 
ANSI escape sequences: 

CHAN OF SS scrn : 
FAR 

so.scrstream.to^ANSI (fs, ts, scrn) 
SEQ 

as. goto. xy (scrn r 0, 0) 

SS .clear .eos (scrn) 

S3 - write . endstream (scrn) 

The key stream and screen stream protocols are identical to those used in the IMS 
D700 Transputer Development System (TDS) and facilitate the porting of 
programs between the TDS and the toolset. 

1.6.1 Naming conventions 

Procedure names always begin with a prefix derived from the first parameter. 
Stream processes, where the SP channel (listed first) is used In combination with 
either the KS or SS protocols, are prefixed with 'so . '. Stream input routines, which 
use only the KS protocol are prefixed with 'k» , ', and stream output routines, which 
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use only the ss protocol, are prefixed with 'ss . '. The KS-to-ss conversion nautine, 
which actually uses both protocols, is prefixed for convenience v^th 'ks.'. 



1.6.2 Stream processes 



Procedure 


Parameter Specifiers 


so . keys treeun . from . Id^d 


CHAN OF SP fS; ts, 
CHAN OF KS keys. out, 
CHAN OF BOOL stopper, 
VAL INT ticks. per. poll 


so . keys tream . from . file 


CHAN OF SP fs, ts, 
CHAN OF KS key 3. out, 

VAL []BYTE filename, 
BYTE result 


so . keystream , from . stdin 


CHAN OF SP fs, ts, 
CHAN OF KS keys. out, 
BYTE result 


ks . keystream . sink 


CHAN OF KS keys 


ks . keystream . to . scrs tream 


CHAN OF KS keyboard, 
CHAN OF SS scm 


ss.scrstream.sink 


CHAN OF SS scm 


so . scrstream . to . file 


CHAN OF SP fs, ts, 
CHAN OF SS scrn, 
VAL []BYTE filename, 
BYTE result 


so . scrstream . to . stdout 


CHAN OF SP fs, ts, 
CHAN OF SS scrn, 
BYTE result 


ss . scrstream . to . array 


CHAN OF SS scrn, 
[]BYTE buffer 


ss . scrstream. from- array 


CHAN OF SS scrn, 
VAL []BYTE buffer 


55 . scrstream . fan . out 


CHAN OF SS scrn, 
screen. outl, 
screen . out2 


ss . scrstream. copy 


CHAN OF SS scrn. in, scrn. out 


so . scrstream. to . ANSI 


CHAN OF SP fs, ts, 
CHAN OF SS scrn 


so, scrstream, to, TVI 920 


CHAN OF SP fs, ts, 
CHAN OF SS scrn 


ss . scrstream .multiplexor 


[]CHAN OF SS screen. in, 
CHAN OF SS screen. out, 
CHAN OF INT stopper 
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Procedure definitions 

so . keys tream . from . kbd 

PROC so.keystream.from.Icbd (CHAN OF SF £s, tsr 

CHAN OF KS keys. out, 
CHAN OF BOOL stopper r 
VAL INT ticks, per, poll) 

Reads cliaracters ^om the keyboard and outputs them one at a time as 
integers on the channel keys, out. It is terminated by sending either a 
TRUE or FALSE on the boolean channel stopper. The procedure polls the 
keyboard at an Interval detemiined by the value of ticks. per. poll, in 
transputer clock cycles, unless keys are available, in which case they are 
read at full speed. It is an error If ticks . per .poll is less than or equal 
to zero. 

After FALSE is sent on the channel stopper the procedure sends the 
negative value ft . terminated on keys . out. 

so . keys tream . from . file 

PI^X: so. keystream. from. file (CHAN OF SP fs, ts, 

CHAN OF KS keys. out, 
VAL []BYTE filename, 
BYTE result) 

Reads lines from the specified text file and outputs them on keys .out. 
Terminates automatically on en^or or when it has reached the end of the file 
and alf the characters have been output on the keys , out channel. A '*c' 
is output to terminate a text line. The negative value ft . teinninated is 
sent on the channel keys . out to mark the end of the file. The result 
returned can take any of the following values: 

spr . ok The operation was successful. 

spr. bad. packet. size Filename too large i.e. SIZE filename 

> sp, max. openname. size. 

spr .bad. name Null file name. 

^ spr . operation . failed The open failed or reading the file failed. 

If result^spr. operation, failed 
then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manual.) 

so . keys tream . from . stdin 

PROC so. keystream. from. stdin (CHAN OF SP fs, ts, 

CHAN OF KS keys. out ^ 
BYTE result) 



72TDS368 01 March 1993 



1 The Occam libraries 



101 



As so. keystream. from. file, but reads from the standard input 
stream. The standard input stream is normally assigned to the keyboard, 
but can be redirected by the host operating system. End of file from 
keyboard will terminate this routine. The result returned may take any of the 
following values: 

spr . ok The operation was successful. 

^spr. operation, failed Reading standard input failed. If result 

^ spr , operation . failed then this 
denotes a server returned failure. (See 
section C.2 in the Tooiset Reference 
Manual.) 

ks . keystream . sink 

PROC ks. key stream. sink (CHAN OF KS keys) 

Reads word length quantities until ft, terminated is received, then 
terminates. 

ks . keystream . to . scrstream 

PROC ks.keystream. to, scrstream (CHAN OF KS keyboard, 

CHAN OF SS scrn) 

Converts key stream protocol to screen stream protocol. The value 
ft . terminated on keyboard terminates the procedure. 

SS , scrstream. sink 

PROC SS. scrstream. sink (CHAN OF SS scrn) 

Reads screen stream protocol and ignores it except for the stream termi- 
nator from SS . write . ends tream which terminates the procedure. 

so . scrstream . to . file 

PROC so. scrstream. to. file (CHAN OF SP fs, ts, 

CHAN OF SS scrn, 
VAL []BYTE filename, 
BYTE result) 

Creates a new file with the specified name and writes the data sent on 
channel scrn to it The scrn channel uses the screen stream protocol 
which is used by all the stream output library routines (and is the same as 
the INMOS TDS screen stream protocol). It terminates on receipt of the 
stream terminator from ss.write.endstream, or on an error condition. 
The result returned can take any of the following values; 
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spr . ok The data sent on a crn was successf u lly 

written to the file, 
spr. bad, packet, size Filename too large I.e. SIZE filename 

> sp. max. opennane. size, 
spr. bad. name Null file name. 

^ spr. operation. failed If result^spr. operation. failed 

then this denotes a server returned 

failure. (See section C.2 in the Toolset 

Reference Manual.) 

If used in conjunction with so . scrstream . fan . out this procedure may 
be used to file a copy of everything sent to the screen. 

so . scrstream. to . stdout 

PROC so.scrstream. to. Stdout (CHAN OF SP fs, ts, 

CHAH OF SS scrn, 
BYTE result) 

Performs the same operation as so . scrstream. to . file, but writes to 
the standard output stream. The standard output stream goes to the 
screen, but can be redirected to a file by the host operating system. The 
result returned can take any of the following values: 

spr . ok The data sent on scrn was successfully 

written to standard output. 

^ spr* operation, failed If results spr. operation, failed 

then this denotes a server returned 
failure. (See section C.2 in the Toolset 
Reference Manual.) 

ss . scrstream . to . array 

PROC ss. scrstream. to. array (CHAN OF SS acrn^ 

[]BYTE buffer) 

Buffers a screen stream whose total size does not exceed the capacity of 
buffer, for debugging purposes or subsequent onward transmission 
using so . scrstream . from . array. The procedure terminates on 
receipt of the stream temninator from ss . write . endstream. 

ss 4 scrstream . from . array 

PROC 88. scrstream. from. array (CHAN OF SS scrn, 

VAL []BYTE buffer) 

Regenerates a screen stream buffered In buffer by a previous call of 
so . scrstream, to , array. Terminates when all buffered data has been 
sent 
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ss . scrstream . f an . out 



PROC ss.scrstream.fan.out (CHAN OF SS scrn, 

screen -outl, 
screen. out2} 

Sends copies of everything received on the input channel scrn to two 
output channels. The procedure terminates on receipt of the stream termi- 
nator from SS .write . endstream without passing on the terminator. 

SS . scrstream . copy 

PROC ss.scrstream.copy (CHAN OF SS scrn- in ^ 

scrn , out) 

Copies screen stream protocol input on scrn. in to scrn. out. Termi- 
nates on receipt of the end-stream terminator from ss. write. ends- 
tream, which is not passed on. 

so . scrs tream . to . ANSI 

PROC so. scrs tream. to. ANSI (CHAN OF SP fs, ts, 

CHAN OF SS scrn) 

Converts screen stream protocol into a stream of bytes according to the 
requirements of ANSI terminal screen protocol. Not all of the screen stream 
commands are supported. 

The following tags are ignored: 

St . ins . char st . reset st , terminates t. help st . claim 

St. key. raw st-key. cooked st. release st, initialise 

The procedure terminates on receipt of the stream tenninator from 
SS . write . endstream. 

so . scrstream . to . TVI 920 

PROC so, scrstream. to. TVT920 (CHAN OF SP fs, ts, 

CHAN OF SS scrn) 

Converts screen stream protocol into a stream of BYTEs according to the 
requirements of TVI 920 (and compatible) lenninals. Not all of the screen 
stream commands are supported. The following tags are ignored: 

st . reset st . terminate st .help st . initialise 

st, key. raw st . key . cooked st. release st. claim 

The procedure terminates on receipt of the stream terminator from 
SS . write . endstream. 
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sa .scrstream. multiplexor 

PROC ss.scrstream.multiplexor { []CHAN OF SS screen. in^ 

CHAN OF SS screen. out ^ 
CHAN OF INT stopper) 

This procedure multiplexes up to 256 screen stream channels onto a single 
screen stream channel. Each change of input channel directs output to the 
next line of the screen, and each such line is annotated at the left with the 
an^y index of the channel used followed by '>'. The tag st, endstream 
is ignored. The procedure is terminated by the receipt of any integer on the 
channel stopper. For n channels, each channel Is guaranteed to be able 
to pass on a message for every n messages that pass through the multi- 
plexor. This is achieved by cycling from the lowest index of screen, in. 
However, stopper always has highest priority. 

16.3 Stream input 

These routines read characters and strings from the input stream, in KS protocol. 



Procedure 


Parameter Specifiers 


ks.read.r^hnr 


CHAN OF KS source, INT char 


ks . read . line 


CHAN OF KS source, INT len, 
[]BYTE line, INT char 


ks . read , int 


CHAN OF KS source, 
INT number, char 


ks . read . int64 


CHAN OF KS source, 
INT64 number, INT char 


ks.read.real32 


CHAN OF KS source, 
REAL32 number, INT char 


ks. read. real 64 


CHAN OF KS source, 
REALe4 niimber, INT char 



Procedure definitions 

ks . read , char 

PROC ks, read. char {CHAN OF KS source, INT char) 

Returns in char the next word length quantity from source. 

ks. read. line 

PROC ks. read. line {CHAN OF KS source, INT len, 
[]BYTE line, INT char) 

Reads text into the array line up to but excluding '*c', or up to and 
excluding any error code. Any '*n* encountered is thrown away, len gives 
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the number of characters in line. If there is an en-or its code is returned 
as char, otherwise the value of char will be INT '*c'. If the array is filled 
before a '*c' is encountered all further characters are ignored, 

ks . read . int 

FROC ks. read. int (CHAN OF KS source, 
INT number, char) 

Skips input up to a digit, #, + or -, then reads a sequence of digits to the 
first non-digit, returned as char, and converts the digits to an integer in 
number . char must be initialized to the first character of the input. If the 
first significant character is a '#' then a hexadecimal number is input, 
thereby allowing the user the option of which number base to use. The 
hexadecimal may be In upper or lower case. 

char Is returned as ft. number .error if the number overflows the INT 
range. 

ks.read.int64 

PROC ks.read.int64 (CHAN OF KS source, 

INT64 number, INT char) 

As ks . read . int, but for 64-bit integers. 

ks . read . real32 

PROC ks.read.real32 (CHAN OF KS source, 

REAL32 number, INT char) 

Skips input up to a digit, ■!■ or -, then reads a sequence of digits with optional 
decimal point and exponent) up to the first invalid character, returned as 
char. Converts the digits to a floating point value in number . char must 
be initialized to the first character of the input If there is an en'or In the 
syntax of the real, ff it is ± infinity, or if more than 24 characters read then 
char is returned as ft . number . error. 

ks,read.real€4 

PROC ks. read, real 64 (CHAN OF KS source, 

REAL64 number, INT char) 

As ks . read. real32, but for 64-bit real numbers. Allows for reading up 
to 30 characters. 



1.6.4 Stream output 

These routines write text, numbers and screen control codes to an output sb^eam 
in ss protocol. 
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1.6 Streamto library 



Procedure 


Parameter Specifiers 


ss. write, char 


CHAN OF SS scrn, VAL BYTE char 


ss,write,nl 


CHAN OF SS scrn 


S3. write. string 


CHAN OF SS scrn, VAL []BYTE str 


ss . write . ends tream 


CHAN OF SS sern 


S3 .write . text . line 


CHAN OF SS scrn, VAL []BYTE str 


ss.write.int 


CHAN OF SS scrn, 

VAL INT nuBiber, width 


ss. write. int64 


CHAN OF SS scrn, VAL INT64 number, 
VAL INT width 


ss. write. hex. int 


CHAN OF SS scrn, 

VAL INT n\j]aber, width 


S3 .write .hex. int 64 


CHAN OF SS scrn, VAL IKT64 number, 
VAL INT width 


ss .write. real32 


CHAN OF SS scrn, VAL REAL32 number, 
VAL INT Ip, Dp 


ss. write. real 64 


CHAN OF SS scrn, VAL HEAL64 number, 
VAL INT Ip, Dp 


S3. goto. xy 


CHAN OF SS scrn, VAL INT x, y 


S3. clear. eol 


CHAN OF SS scrn 


ss. clear .eos 


CHAN OF SS scrn 


ss.beep 


CHAN OF SS scrn 


ss.up 


CHAN OF SS scrn 


ss.down 


CHAN OF SS scrn 


ss.left 


CHAN OF SS scrn 


ss . right 


CHAN OF SS scrn 


ss . insert . char 


CHAN OF SS scrn, VAL BYTE ch. 


sa. delete. ehr 


CHAN OF SS scrn 


ss. delete. chl 


CHAN OF SS scrn 


SS- ins. line 


CHAN OF SS scrn 


S3. del. line 


CHAN OF SS scrn 



Procedure definitions 

ss . write . char 

PROC ss. write, char (CHAN OF SS scrn, 
VAL BYTE char) 

Sends the ASCII value char on scrn, in scrstream protocol, to the 
current position in the output line. 
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ss.write,nl 

PROC sg.write.nl (CHAN OF SS scrn) 

Sends "*c*n'' to scrn. 

SS . write . string 

PROC SS. write, string (CH3Uf OF SS scrn, 

VAL []BYTE str) 

Sends all characters in str to scrn. 
SS .write . endstream 

PROC s s. wri t e. ends tr earn (CHAN OF SS scrn) 

Sends a special stream terminator value to scrn. 

ss * write . text . line 

PROC ss.write. text, line (CHAN OF SS scm^ 

V3U: [J BYTE str) 

Sends all of str to scrn ensuring that, whether or not the last character 
of str is '*c', the last two characters sent are "*c*n". 

33. write, int 

PROC S3. write. int (CHAN OF SS scrn, 

VAL INT number, width) 

Converts number into a sequence of ASCII decimal digits padded out with 
leading spaces and an optional sign to the specified field width, width, if 
necessary. If the number cannot be represented in width characters it is 
widened as necessary; a zero value for width will give minimum width. 
The converted number is sent to scrn. A negative value for width is an 
en'or. 

33. write. int64 

PROC ss. write. int 64 (CHAN OF SS scrn^ 
VAL INT64 number r 
VAL INT width) 

As SS .write, int but for 64-bit integers. 

SS .write .hex. int 

PROC SS. write. hex. int (CHAN OF SS scrn, 

VAL INT number^ width) 
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Converts number into a sequence of ASCII hexadecimal digits, using 
uppercase letters, preceded by '#'. The total numberofcharacterssentis 
always width + 1, padding out with '0' or 'F' on the left if necessary. The 
number is truncated at the left if the field is too narrow, thereby allowing the 
less significant part of any number to be printed. The converted number is 
sent to scm. A negative value for width Is an error. 

3s , write . hex , int64 

PROC ss. write. hex. int64 (CHAN OF SS scrn, 

VAL INT 64 number, 
VAL INT width) 

As SS . write . hex . int but for 64-bit Integer values. 

S0 . wr i te . real 32 

PROC SS. write, real32 {CHAN OF SS scrn, 

VAL REAL32 number, 
VAL INT Ip, Dp) 

Converts number into an ASCII string formatted using ip and Dp, as 
described forREAL32T0STRiNG {see section 1.8). The converted number 
is sent to scrn. If thefomnatted fomi of number is larger than 24 characters 
then this procedure acts as an invalid process. 

SS .write . real64 

PROC S3.write.real64 (CHAN OF SS scrn, 

VAL REAL64 number ^ 
VAL INT Ip, Dp) 

As for S8.write.real32 but for 64-bit real values. See section 1.8, 
REAL32T0STRING for details Of the formatting effect of ip and Dp. If the 
formatted form of number is larger than 30 characters then this procedure 
acts as an invalid process. 

3s.goto.xy 

PROC ss.goto,xy (CHAN OF SS scrn, VAL INT X, y) 

Sends the cursor to screen position (x,y). The origin (0,0) is at the top left 
comer of the screen. 

SS. clear. eol 

PROC S5. clear. eol (CHAN OF SS scrn) 

Clears screen from the cursor position to the end of the current line. 
SS. clear .eos 

PROC ss. clear. eos (CHAN OF SS scrn) 

Clears screen from the cursor position to the end of the current line and all 
lines below. 
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ss .beep 

FROC ss.beep (CHAN OF SS scm) 

Sends a bell code to the termlnat. 
ss.up 

PROC as. up {CHAN OF SS scrn) 

Sends a command to the terminal to move the cursor one line up the 
screen. 

SS .down 

PROC ss.down (CHAN OF SS scrn) 

Sends a command to the terminal to move the cursor one line down the 
screen. 

ss.left 

PROC ss.left (CHAN OF SS scrn) 

Sends a command to the temiinal to move the cursor one place left. 
SS. right 

PROC SS. right (CHAN OF SS scrn) 

Sends a command to the lenninal to move the cursor one place right. 

S3. insert. char 

PROC 3 s. insert. char (CHAN OF SS scrn, 
VAL BYTE Ch) 

Sends a command to the terminal to move the character at the cursor and 
all those to the right of it one place to the right and inserts char at the 
cursor. The cursor moves one place right. 

S3.delet:e.chr 

PROC SS. delete. chr (CHAN OF SS scrn) 

Sends a command to the terminal to delete the character at the cursor and 
move the rest of the line one place to the left. The cursor does not move. 

S3.delei:e.chl 

PROC SS. delete. chl (CHAN OF SS scrn) 

Sends a command to the terminal to delete the character to the left of the 
cursor and move the rest of the line one place to the left. The cursor also 
moves one place left, 
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S3 .ins .line 

PROC S3. ins. line (CHAN OF SS scrn) 

Sends a command to the tem:iinal to move all lines below the current line 
down one line on the screen, losing the bottom line. The current Eine 
becomes blank. 

SS. del. line 

PROC SS. del. line (CHAN OF SS scrn) 

Sends a command to the terminal to delete the current line and move all 
lines below it up one line. The bottom line becomes blank. 
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17 String handling library 

Library: string, lib 

This library contains functions and procedures for handling strings and scanning 
lines of text. They assist with the manipulation of character strings such as names, 
commands^ and l^eyboard responses. The library provides routines for: 

• Identifying characters 

• Comparing strings 

• Searching strings 

• Editing strings 

• Scanning lines of text 



Result 


Function 


Parameter specifiers 


BOOL 


is. in. range 


VRL BYTE char, bottom , top 


BOOL 


is . upper 


VAL BYTE char 


BOOL 


is . lower 


VAL BYTE char 


BOOL 


is. digit 


VAL BYTE char 


BOOL 


is. hex. digit 


VAL BYTE char 


BOOL 


is. id* char 


VAL BYTE char 


INT 


compare . strings 


VAL I] BYTE strl, str2 


BOOL 


eqstr 


VAL []BYTE si, s2 


INT 


string.pos 


VAL []BYTE search, str 


INT 


char.pos 


VAL BYTE search 
VAL [IBYTE str 


INT, BYTE 


search. match 


VAL []BYTE possibles, str 


INT, BYTE 


search . no .match 


VAL []BYTE possibles, str 
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Procedure 


Parameter Specifiers 


str. shift 


[JBYTE str, 

VAL INT start, len, shift, 

BOOL not. done 


delete . string 


INT len, []BYTE str, 
VAL INT start, size, 
BOOL not. done 


insert. string 


VAL HBYTE new.str, 

INT len, []BYTE str, 

VAL INT start, BOOL not. done 


to, upper .case 


[jBYTE str 


to . lower . case 


[IBYTE str 


append . char 


INT len, []BYTE str, 
VAL BYTE char 


append. text 


INT len, []BYTE str, 
VAL I] BYTE text 


append. Int 


INT len, []BYTE str, 
VAL INT nuiober, width 


append. int 64 


INT len, []BYTE str, 

VAL INT 64 number, VAL INT width 


append , hex . int 


INT len, I] BYTE str, 
VAL INT number, width 


append , hex . int64 


INT len, []BYTE str, 
VAL INT64 number, 
VAL INT width 


append. real 3 2 


INT len, []BYTE str, 
VAL RKAT.32 number, 
VAL INT Ip, Dp 


append. real 64 


INT len, []BYTE str, 
VAL REAL64 number, 
VAL INT Ip, Dp 


next .word. from, line 


VAL []BYTE line, 

INT ptr, len, 

I] BYTE word, BOOL ok 


next . int . from . line 


VAL []BYTE line, 

INT ptr, number f BOOL olc 



1.7.1 Character identification 

is . in . range 

BOOL FONCTION is. in. range (VAL BYTE char, bottom, top) 

Returns TRUE if the value of char is in the range defined by bottom and 
top inclusive, otherwise returns FALSE. 
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is, upper 

BOOL FDNCTION is. upper (VAL BYTE char) 

Returns TRUE if char is an ASCII upper case letter, otherwise returns 
FALSE. 

is . lower 

BOOL FUNCTION is. lower (VAL BYTE char) 

Returns true if char is an ASCII lower case letter, otherwise returns 
FALSE. 

is. digit 

BOOL FUNCTION is. digit {VAL BYTE char) 

Returns TRUE if char is an ASCII decimal digit, otherwise returns FALSE. 

is. hex. digit 

BOOL FUNCTION is. hex. digit (VAL BYTE char) 

Returns TRUE if char is an ASCII hexadecimal digit, otherwise returns 
FALSE. Upper or lower case letters A-F are allowed, 

is, id. char 

BOOL FUNCTION is. id. char (VAL BYTE char) 

Returns TRUE if char is an ASCI I character which can be part of an Occam 
name; othemse returns FALSE. 

1.7.2 String comparison 

These two procedures allow strings to be compared for order or for 
equality. 

compare . strings 

INT FUNCTION compare . strings (VAL I]BYTE strl, str2) 

This general purpose ordering function compares two strings according to 
the lexicographic ordering standard. (Lexicographic ordering is the 
ordering used in dictionaries etc., using the ASCII values of the bytes). It 
returns one of the 5 results 0, 1, -1, 2, or -2, as follows: 

The strings are exactly the same in length and content. 

1 str2 is a leading substring of strl 
-1 strl is a leading substring of str2 

2 strl Is lexicographjcady later than str2 
-2 str2 is lexicographically later than strl 
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So If sis "abed": 

compare . strings ("abc", [a FROM FOR 3]) =0 

compare, strings ("abc", [s FROM FOR 2]) =1 

compare. strings ("abc", s) - ~1 

compare . strings ("be" , u) ~ 2 

compare . strings ( "a4 " / s ) = -2 

eqstr 

BOOL FUNCTION eqstr (VAL [jBYTE sl,s2) 

This is an optimized test for string equality. It returns TRUE if the two strings 
are the same size and have the same contents, false otherwise. 

1.7.3 String searching 

These procedures allow a string to be searched for a match with a single 
byte or a string of bytes, for a byte which is one of a set of possible bytes, 
or for a byte which is not one of a set of bytes. Searches insensitive to 
alphabetic case should use to . upper . case or to . lover , case on both 
operands before using these procedures. 

string. pos 

INT FUNCTION string.poa (VIIL []BYTE search, str) 

Returns the position in str of the first occurrence of a substring which 
exactly matches search. Returns -1 if there is no such match. 

char .pos 

INT FUNCTION char.pos (VAL BYTE search, 

VAL []BYTE str) 

Returns the position in str of the first occurrence of the byte search. 
Returns -1 if there is no such byte. 

search, malx^h 

INT, BYTE FUNCTION search, match 

(VAL []BYTE possibles, str) 

Searches str for any one of the bytes in the array possibles. If one is 
found its index and Identity are returned as results. If none is found then 
-1,255(BYTE) are returned. 

search . no . match 

INT, BYTE FUNCTION search . no . match 

(VAL []BYTE possibles, str) 
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Searches str for a byte which does not match any one of the bytes In the 
array possibles. If one is found its Index and identity are returned as 
results. If none is found then -1 ,255(byte) are returned. 



1.7.4 String editing 

These procedures allow strings to be edited. The string to be edited is 
stored in an array which may contain unused space. The editing operations 
supported are: deletion of a number of characters and the closing of the 
gap created; Insertion of a new string starting at any position within a string, 
which creates a gap of the necessary size. 

These two operations are supported by a lower level procedure for shifting 
a consecutive substring left or right within the array. The lower level proce- 
dure does exhaustive tests against overflow. 

str. shift 

PROC str, shift ([JBYTE str, VAL INT start, 
len, shift, BOOL not. done) 

Takes a substring [str FROM start FOR len] , and copies it to a position 
shift places to the right Any implied actions involving bytes outside the 
string are not performed and cause the error flag not, done to be set to 
TRUE. Negative values of shift cause leftward moves. 

delete . string 

EROC delete. string fINT len, []BYTE str, 
VAL INT start, size, 
BOOL not. done) 

Deletes size bytes from the string str starting at str [start] . There are 
initially len significant characters in str and it is decremented appropri- 
ately. If start Is outside the string, or start + size is greater than len, 
then no action occurs and not . done is set to TRUE. 

insert , string 

PROC insert. string (VAL []BYTE new. str, INT len, 
[]BYTE str, VAL INT start, 
BOOL not. done) 

Creates a gap in str after str [start] and copies the string new . str 
into it. There are initially len significant characters in str and len is 
incremented by the length of new. str inserted. Any overflow of the 
declared size of str results in truncation at the right and setting not . done 
to TRUE. This procedure may be used for simple concatenation on the right 
by setting start = len or on the left by setting st:art = 0. This method 
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of concatenation difTers from that using the append procedures In that it 
can never cause the program to stop, 

to. upper. case 

FROC to . u^er . case ( [ ] BYTE str) 

Converts all alphabetic characters in str to uppercase. All other charac- 
ters are left unaltered, 

to , lower * case 

PROC to. lower. case {[IBYTE str) 

Converts all alphabetic characters in str to lower case. M other charac- 
ters are left unaltered. 

append . char 

FROC a£^>end.char (INT len, []BYTE str, 
VAL BYTE char) 

Writes a byte char into the array str at str[lenl. len is incremented by 
1, Behaves like STOP if the an^y overflows. 

append, text 

PROC append, text (INT len, [IBYTE str, 
VAL []BYTE text) 

Writes a string text into the an^y str, starting at s tr[len] and computing 
a new value for len. Behaves like STOP if the an'ay overflows. 

append * int 

PROC append. int (INT len, []BYTE str, 

VAL INT number, width) 

Converts number into a sequence of ASCII decimal digits padded out with 
leading spaces and an optional sign to the specified field width, width, if 
necessary. If the number cannot be represented in width characters it is 
widened as necessary. A zero value for width will give minimum width. 
The converted number is written into the array st:r starting at str [len] 
and len is incremented. Behaves like STOP if the an-ay overflows or if 
width < 0. 

append . int64 

PROC append. int 64 (INT len, []BYTE str^ 
VAL INT64 number, 
VAL INT width) 

As append, int but for 64-bit integers. 
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append .hex . int 

PROC append. hex. int (INT len, []BYTE str, 

VAL INT number f width) 

Converts number into a sequence of ASCII hexadecimal digits, using 
upper case letters, preceded by '#', The total number of characters set is 
always width+1, padding out with '0' or 'F' on the left if necessary. The 
number is truncated at the left if the field is too nan-ow, thereby allowing the 
less significant part of any numberto be printed. The converted number Is 
written into the array str starting at str[len] and len is incremented. 
Behaves like stop if the array overflows or if width < 0. 

append . hex . int64 

PROC append. hex. int64 (INT Ion, []BYTE str, 

VAL INT64 number, 
VAL INT width) 

As append , hex . int but for 64-bit integers. 

append, real 32 

PROC append. real32 (INT len, []BYTE str, 
VAL REAL32 number, 
VAL INT Ip, Dp) 

Converts number into a sequence of ASCI I characters formatted using Ip 
and Dp as described under REAL32TOSTRIKG {see section 1 .8). 

The converted number is written into the an-ay str starting at str[lenj 
and len is incremented. Behaves like STOP if the array overflows, 

append . real 64 

PROC append. real64 {INT len, []BYTE str, 
VAL REAL64 number, 
VAL INT Ip, Dp) 

As append, real32, but for 64-bit real values. The formatting variables 
Ip and Dp are described under real32TOSTRING (see section 1.8). 



1.7.5 Line parsing 

Depending on the initial value of the variable ok these two procedures 
either read a line serially, returning the next word and next integer respec- 
tively, or the procedures act almost like a SKIP (see below). The user 
should initialize the variable ok as appropriate. 
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next . word. from, line 

PEQC next* word, from. line (VAL []BYTE line, 

INT ptr, len, 
[]BYTE word, 
BOOL ok] 

If ok is passed in as TRUE, on entry to the procedure, skips leading spaces 
and horizontal tabs and reads the next word from the string line. The 
value of ptr is the starting point of the search. A word continues until a 
space or tab or the end of the string line is encountered. If the end of the 
string is reached without finding a word, the boolean ok is set to FALSE, 
and len is 0. If a word Is found but is too large for word, then ok is set to 
FALSE, but len will be the length of the word that was found; otherwise the 
found word will be in the first len bytes of word. The index ptr is updated 
to be that of the space or tab immediately after the found word, or is SIZE 
line. If ok is passed in as FALSE, len is set to 0, ptr and ok remain 
unchanged, and word Is undefined. 

next . int . from . line 

PROC next. int, from. line (VAL []BYTE line, 

INT ptr, number J, 
BOOL ok) 

If ok is passed in as TRUE, on entry to the procedure, skips leading spaces 
and horizontal tabs and reads the next integer from the string line. The 
value of ptr is the starting point of the search. The integer is considered 
to start with the first non-space, non-tab character found and continues 
until a space or tab or the end of the string line is encountered. If the first 
sequence of non-space^ non-tab characters does not exist, does notfomi 
an integer, or forms an integer that overflows the INT range then ok is set 
to FALSE, and number is undefined; otherwise ok remains TRUE, and 
number is the integer read. A *+' or -' may be the first character of the 
integer. The indexptr is updated to be that of the space or tab immediately 
after the found integer, or is SIZE line. If ok is passed in as FALSE, then 
ptr and ok remain unchanged, and number is undefined. 
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1.8 String conversion library 

Library: convert. lib 

This library contains procedures for converting numeric values to strings and vice 
versa. String to numeric conversions return two results, the converted value and 
a boolean error indication. Numeric to string conversions return the converted 
string and an integer which represents the numberof significant characters written 
into the string. 

These routines are also described in appendix of the OCCSm 2 Reference 

Manual. 



Procedure 


Parameter Specifiers 


INTTOSTRING 


INT len, []BYTE string, VAL INT n 


INT16T0STRING 


INT len, [JBYTE string, VAL INT16 n 


INT32T0STRING 


INT len, []BYTE string, VAL INT32 n 


INT64TOSTRING 


INT len, [JBYTE string, VAL INT64 n 


HEXTOSTRING 


INT len, [JBYTE string, VAL INT n 


HEX16T0STRING 


INT len, [JBYTE string, VAL INT16 n 


HEX32T0STRING 


INT len^ [JBYTE string, VAL INT32 n 


HEX64TOSTRING 


INT len, [IBYTE string, VAL INT64 n 


REAL32T0STRING 


INT len, [JBYTE string, VAL REAL32 X, 
VAL INT Ip, Dp 


REJVL64TOSTRING 


INT len, [JBYTE string, VAL REAL64 X, 
VAL INT Ip, Dp 


BOOLTOSTRING 


INT len, [JBYTE string, VAL BOOL b 


STRINGTOINT 


BOOL Error, INT n, VAL [JBYTE string 


STRINGT0INT16 


BOOL Error, INT16 n, VAL [JBYTE string 


STRINGTOINT32 


BOOL Error, INT32 n, VAL [JBYTE string 


STRINGTOINT64 


BOOL Error, INT64 n, VAL [JBYTE string 


STRINGTOHEX 


BOOL Error, INT n, VAL [JBYTE string 


STRINGT0HEX16 


BOOL Error, INT16 n, VAL [JBYTE string 


STRIKGTOHEX32 


BOOL Error, INT32 n, VAL [JBYTE string 


STRIKGT0HEX64 


BOOL Error, INT64 n, VAL [JBYTE string 


STRINGTOREAL32 


BOOL Error, REAL32 X, VAL [JBYTE string 


STRINGTOREAL64 


BOOL Error, REAL64 X, VAL [JBYTE string 


STRINGTOBOOL 


BOOL Error, b, VAL [JBYTE string 
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Procedure definitions 

INTTOSTRING 

PROC INTTOSTRING (INT len, []BYTE string, 
VAX. INT n} 

Converts an integer value to a string. The procedure returns the decimal 
representation of n in string and the number of characters in the repre- 
sentation, in len. If string is not long enough to hold the representation 
then this routine acts as an invalid process. 

Similar procedures are provided for the types INT16, INT32, and int64. 

INT16T0STRING 

PROC INT16T0STRING (INT len, []BYTE string, 
VAL INT16 n) 

As INTTOSTRING but for 16-bJt integers. 

INT32TOSTRING 

PROC INT32TOSTRING (INT len, []BYTE string, 
VAL INT32 n) 

As INTTOSTRING but for 32-bit integers, 

INT64TOSTRING 

PROC INT64TOSTRIKG (INT len, []BYTE string, 
VAL INTe4 n) 

As INTTOSTRING but for 64-bit integers. 

HEXTOSTRING 

PROC HEXTOSTRING (INT len, [JBYTE string, 
VAL INT n) 

The procedure returns the hexadecimal representation of n in string and 
the number of characters in the representation, in len. All the bits of n, (in 
4- bit wide wonJ lengths) are output so that leading zeroes or 'F's are 
included. The number of characters will be the number of bits in an INT 
divided by four. A '#* is not output by the hextostring procedure. If 
string is not long enough to hold the representation then this routine acts 
as an invalid process. 

Similar procedures are provided for the types KEX16, HEX32 and HEX64. 

HEX16T0STRING 

PROC HEX16T0STRING (INT len^ []BYTE string, 
VAL INT16 n) 

As HEXTOSTRING but for 16-bit integers. 
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HEX32TOSTRING 

PROC HEX32TOSTRING (INT len, []BYTE string, 
VAL IHT32 n) 

As HEXTOSTRING but for 32-bit integers. 

HEX64TOSTRING 

PROC HEX64TOSTRING (INT len, []BYTE string, 
VAL INT64 n) 

As HEXTOSTRING but fof 64-bit integers. 

REAL32T0STRING 

PRCX: REAL32T0STRING (IKT len, []BYTE string, 
VAL REAL32 X, 
VAL INT Ip, Dp) 

Converts a 32-bit real number (represented in single precision IEEE 
format) to a string of ASCII characters, len i^ the number of characters 
(bytes) of string used for the fomiatted decimal representation of the 
number. (The following description applies to and notes the differences 
between this procedure and real64tostring). 

The string must match the format for occann real literals as defined in the 
OCcam 2 Reference Manual, p 123, for example, 1.2E+2. 

Depending on the value of X and the two formatting variables Ip and Dp 
the procedure will use either a fixed or exponential format for the output 
string. These formats are defined as follows: 

Fixed : First, either a minus sign or space (an explicit plus sign 

is not used), followed by a fraction in the form 
<digits> . <digits>. Padding spaces are added to the left 
of the sign indicator, as necessary, (ip gives the number 
of places before the point and Dp the number of places 
after the point). 

Exponential : First, either a minus sign or space (again, an explicit plus 
sign is not used), followed by a fraction in the form 
<digit> . <digits>, the exponential symbol (E), the sign of 
the exponent (explicitly plus or minus), then the expo- 
nent, which is two digits for a REAL32 and three digits for 
a R£AL64. (Dp gives the number of digits in the fraction 
{1 before the decimal point and the others after)). 

Possible combinations of Ip and Dp fall into three categories, described 
below. Note: the tenn *Free format' means that the procedure may adopt 
either fixed or exponential format, depending on the actual value of x. 
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1 If lp=0, Dp=0, then free format is adopted. Exponential format is used 
if the absolute value of X is less than 10^, but non-zero, or greater 
than 10^ (forREAL32), or greater than 10"^^ (forREAL64): otherwise 
fixed format is used. 

The value of len is dependent on the actual value of x with trailing 
zeroes suppressed. The maximum length of the result is 15 or 24, 
depending on whether it is RE&L32 or R£AL64 respectively. 

Ifx is 'Not-a-Number' or infinity then the string will contain one of the 
following: 'inf *, -inf ' or UaK', (excluding the quotes). 

2 If lp>0, Dp>0, fixed format is used, unless the value needs more than 
Ip significant digits before the decimal point, in which case, exponen- 
tial format is used. If exponential does not fit either, then a signed 
string 'Ov' is produced. The length is always Ip + Dp + 2 when ip>0, 
Dp>0. 

If X is 'Not-a-Number' or infinity tiren the string will contain one of the 
following: 'Inf, -Inf or 'NaM', (exduding the quotes) and padded 
out by spaces on the right to fill the field width. 

3 If lp=0, Dp>0, then exponential format is always used. The length of 
the result is Dp + 6 or Dp + 7, depending on whether X is a REflli32 
orREAL64j respectively. 

If lp=0, Dp=1, then a special result is produced consisting of a sign, 
a blank, a digit and the exponent. The length is 7 or 8 depending on 
whether X is a KEAL32 orF£AL64. Note: this result does not conform 
to the Occam format for a real. 

Ifx is 'Not-a-Number' or infinity then the string will contain one of the 
following: *inf , '-inf or UaN', (excluding the quotes) and padded 
out by spaces on the right to fill the field width. 

Ail other combinations of Ip and Dp are errors. 

If string is not long enough to hdd the requested formatted real number as 
a string then these routines act as invalid processes. 

REAL64TOSTRING 

PROC REAL64TOSTRING (INT len, []BYTE string, 
VAL P£AL64 X, 
VAL INT Ip; Dp) 

As REAL32TOSTRING but for 64-bit numbers. 
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BOOLTOSTRING 

PROC BOOLTOSTRING (INT len, []BYTE string, 
VAL BOOL b) 

Converts a boolean value to a string. The procedure returns 'TRUE* in 
string if b is TRUE and 'FALSE' Otherwise, len contains the number of 
characters in the string returned. If string is not long enough to hold the 
representation then this routine acts as an invalid process. 

STRINGTOINT 

PROC STRINGTOINT (BOOL Error, INT n, 
VAL []BYTE string) 

Converts a string to a decimal integer The procedure returns in n the value 
represented in string, error is set to TRUE if a non-numeric character 
is found in string or if string Is empty. + or a - are allowed in the first 
character position, n will be the value of the portion of string up to any 
illegal characters, with the convention that the value of an empty string is 
0. error is also set to TRUE if the value of string overflows the range of 
INT, In this case n will contain the lowon:ler bits of the binary representation 
of string, error is set to FALSE in all other cases. 

Similar procedures are provided for the types INT16, INT32, and INT64. 

STRINGT0INT16 

PROC STRINGT0INT16 (BOOL Error, IKT16 n, 
YAL []BYTE string) 

As STRINGTOINT but converts to a 16-bit integer. 

STRINGTOINT32 

PROC STRINGTOINT32 (BOOL Error, INT32 n, 
VAL [JBYTE string) 



As STRINGTOINT but converts to a 32-bit integer. 

STRINGTOINT 6 4 

PROC STRINGTOINT64 (BOOL Error, INT64 n, 
VAL []BYTE string) 

As STRINGTOINT but converts to a 64-bit integer. 
72 TDS 368 01 March 1993 



124 1.8 String conversion library 



STRINGTOHEX 

PROC STRINGTOHEX (BCX)L Error, INT n, 
VAL []BYTE string) 

The procedure returns in n the value represented by the hexadecimal 
string. No '#' is allowed in the input and hex digits must be in uppercase 
(A to F) rather than lower case (a to f ). error is set to true if a non-hexa- 
decimal character is found in string, or if string is empty, n will be the 
value of the portion of string up to any illegal character with the conven- 
tion that the value of an empty string is 0. error is also set to TRUE if the 
value represented by string overflows the range of int. In this case n 
will contain the low order bits of the binary representation of string. In all 
other cases error is set to FALSE. 

Similar procedures are provided for the types HEX16, HEX32, and HEX 64. 

STRINGT0HEX16 

PROC STRINGT0HEX16 (BOOL Error, INT16 n, 

VAL tJBYTE string) 

As STRINGTOHEX but converts to a 1 6-bit integer. 

STRINGTOHEX32 

PROC STRINGT0HEX32 {BOOL Error, 1NT32 n, 
VAL []BYTE string) 

As STRINGTOHEX but converts to a 32-bit integer. 

STRINGTOHEX64 

PROC STRINGTOHEX64 (BOOL Error, INT64 n, 
VAL []BYTE string) 

As STRINGTOHEX but converts to a 64-bil integer 

STRINGT0REAL32 

PROC STRINGTOREAL32 (BOOL Error, REAL32 X, 
VAL []BYTE string) 

Converts a string to a 32-bit real number. This procedure takes a string 
containing a decimal representation of a real number and converts it into 
the corresponding real value. If the value represented by string over- 
flows the range of the type then an appropriately signed infinity is returned. 
Errors in the syntax of string are signalled by a 'Not-a-Number' being 
returned and error being set to TRUE. The string is scanned from the left 
as far as possible while the syntax is still valid, if there are any characters 
after the end of the longest con*ect string then error is set to TRUE, other- 
wise it is FALSE. For example if string was "12.34E+2+1.0" then the 
value retumed would be 12.34 x 10^ with error set to TRUE- 
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STRINGTOREAL64 

PROC STRIN6T0REAL64 (BOOL Error, REAL64 X, 
VAL I ] BYTE string) 

As STRINGTOREAL32 but converts to a 64-bit number. 

STRINGTOBOOL 

PROC STRINGTOBOOL (BOOL Error, b, 

VAL []BYTE string) 

Converts a string to a boolean value. The procedure returns true in b if 
the first four characters of string are 'TRUE' and FALSE if the first five 
characters are 'false'; b is undefined in other cases. TRUE is returned in 
error If string is not exactly 'TRUE' or 'FALSE'. 
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1.9 Block CRC library 

Library: crc.lib 

The block ORG library provides two functions for calculating cyclic redundancy 
check values from byte strings. Such values can be of use in, for example, the 
generation of the frame check sequence (FCS) in data communications. 

A cyclic redundancy check value is the remainder from modulo 2 poiynomial divi- 
sion. Consider bit sequences as representing the coeffidents of polynomials; for 
example^ the bit sequence 1 1 001 00 (where the leading bit is the most significant 
bit (msb)) coresponds to P(x) = x^+x^+x^. The routines in the library calculate 
the remainder of the modulo 2 polynomial division: 

{x^*''H(x) + x"F(x))/G(x) 

where: F(x) coresponds to InputString 

G(x) corresponds to PolynomialSenerator 

H(x) corresponds to OldCRC 

k is the number of bits In Input;String 

n is the word size in bits of the processor used (i.e. n is 16 or 32). 

(OldCRC can be viewed as the value that would be pre-loaded into the cyclic shift 
register that is part of hardware implementations of CRC generators.). 

When representing G{x) in the word PolynomialG«nerat:or, note that there is 
an understood bit before the msb of PolyncanialGenerator. For example, on 
a 16-bit processor, with G{x) =x^^+ x^^+ x^* 1, which is #11021, then Poiyno- 
mialGenerator must be assigned #1021 , because the bit corresponding to x^^ 
is understood. Thus, a value of #9603 for PolynomialGenerator, corresponds 
to G(x) = x^^+ x^^-i- x^^+x^<^ + x^ + X + 1, for a 16-bit processor 

A similar situation holds on a 32-bit processor, so that: 

G(x) = x^2 + x^^+x^^+x^2+x*^+x^2+xff + x^o+xS + x^+x5+x^+x2 + x+1 

is encoded in PoXynomialGenerator as#04C11DB7. 

It is possible, however, to calculate a 16-bit CRC on a 32-bit processor. For 
example, if G(x) = x^^+ x^^+ x^+^, then PolynomialGenerator is #1 021 0000. 
This is because the most significant 16 bits of the 32-bit integer fomi a 16-bit gener- 
ator; the least significant 16 bits of OldCRC fomi the initial CRC value; and the 
calculated CRC is the most significant 16 bits of the result from crcfrommsb and 
the least significant 1 6 bits of the result from CRCFROMLSB. 

1.9.1 Example of use 

Suppose it is required to transmit information between two 32-bit transputers, and 
the message that is to be transmitted is the byte array [data from 4 FOR 
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size. message], where there are size. message bytes in the message. Both 
the transmitter and receiver use the same 32-bit generating polynomial and 
oidCRC value. There are two methods for the receiver to check messages: 

First CRCFROMMSB is given the message as an input string, the result is placed into 
the first four bytes of data and the message is sent. The receiver can either 

Give the received data (which is (size. message + 4) bytes long) to 
CRCFROMMSB and expect a result of zero, 

or: 

Give the received [data FROM 4 FOR (size. message)] to 
CRCFROMMSB and check that the result is equal to the INT contained in the 
received [data FROM FOR 4]. 

These methods of checking are equivalent. If the check falls then the transmitted 
data was corrupted and re-transmission can be requested; if the check passes 
then it is most probable that the data was transmitted without corruption - just how 
probable depends on many factors, associated with the transmission media. 

Note: The Occam predefines crcbyte and CRCWORD can be chained together 
to help calculate a CRC from a byte string, and this is indeed the use to which they 
are put in crcfrommsb and crcfromlsb. However, because these latter routines 
shift the polynomial F{x} corresponding to inputstring by x", these routines 
should not be chained together over segments of a byte string to find its CRC; the 
whole string must be used in a single call to crcfrommsb or crcfromlsb. 

1.9.2 Function definitions 

CRCFROMMSB 

INT FUNCTION CRCFROMMSB (VAL []BYTE InputString, 

VAL INT PolynomialGenerator, 
VAL INT OldCRC) 

This routine is intended for strings in normal transputer fomat (little-en- 
dian). The most significant bit of the given string is taken to be blt-16 or 
bit-32, depending, that is, on the word size of the processor, of 
InputString[{SIZE Inputstring) - 1], 

PolynomialGenerator, OldCRC and the result are all also in normal 
transputer fomat (little-endian). 

CRCFROMLSB 

INT FUNCTION CRCFROMLSB (VAL []BYTE Inputstring, 

VAL INT PolynomialGenerator, 
VAL INT OldCRC) 

This routine accommodates strings in big-endian fomat. The most signifi- 
cant bit of Inputstring iS taken to be bit of InputString[0] . The 
generated ORG is given in big-endian format. PolynomialGenerator 
and OldCRC are tai^en to be in little-endian fomat. 
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1.10 Extraordinary link handling library 

Library: xlinlc.lib 

The extraordinary link handling library contains routines for handling communica- 
tion failures on a link. Four procedures are provided to allow failures on input and 
output channels to be handled by timeout or by signalling the failure on another 
channel. Afifth procedure allows the channel to be reset. Use of these routines is 
described in section 13.5 of the User Guide. 



Procedure 


Parameter Specifiers 


InputOrFail . t 


CHlUf OF ANY c, []BYTE mess, 

TIMER t, VAL INT time, BOOL aborted 


OutputOrFail . t 


CHAN OF ANY c, VAL []BYTE mess, 
TIMER t, VAL INT timn, BOOL aborted 


InputOrFail. c 


CHAN OF ANY c, []BYTE mess 
CHAN OF INT kill, BOOL aborted 


OutputOrFail. c 


CHAN OF ANY c, VAL []BYTE mess, 
CHAN OF INT kill, BOOL aborted 


Reinitialise 


CHAN OF ANY C 



CAUTION: 

Use of the routines in xlink . lib during interactive debugging will lead to unde- 
fined results. 

1.10.1 Procedure definitions 

The first four of these procedures take as parameters a link channel c (on which 
the communication is to take place), a byte vector mess (the object of the commu- 
nication), and the boolean variable aborted. The choice of a byte vector for the 
message allows an object of any type to be passed along the channel providing 
it is retyped first, aborted is set to TRUE if the communication times out or is 
aborted; otherwise it is set to FALSE. 

Note: In rare circumstances aborted may be set to TRUE even though the 
communication is successful. This happens if the communication terminates 
successfully in the interval between the timeout/abort and channel renitialization. 
The likelihood of this event is very small. 

InputOrFail. t 

PROC InputOrFail. t {CHAN OF ANY c, []BYTE mess, 
TIMER t, VAL INT time, 
BOOL aborted) 

This procedure is used for communication where failure is detemiined by 
a timeout. It takes a timer parameter t, and an absolute time time. The 
procedure treats the communication as having failed when the Ume as 
measured by the timer t is after the specified time time. If the timeout 
occurs then the channel c is reset and this procedure terminates. 
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OutputOrFail.t 

PROC OutputOrFail.t (CHAN OF ANY c, 

VAL []BYTE mess, 
TIMER t, VAL INT time, 
BOOL aborted) 

This procedure is used for communication where failure is determined by 
a timeout. It takes a timer parameter t, and an absolute time time. The 
procedure treats the communication as having failed when the time as 
measured by the timer t is AFTER the specified time time. If the timeout 
occurs then the channel c is reset and this procedure terminates. 

InputOrFail . c 

PROC InputOrFail. c (CHAN OF ANY c, []BYTE mess, 
CHAN OF INT kill, 
BOOL aborted) 

This procedure provides, through an abort control channel, for communica- 
tion failure on a channel expecting an input. This is useful if failure cannot 
be detected by a simple timeout Any integer on the channel kill will 
cause the channel c to be reset and this procedure to terminate. 

OutputOrFail.c 

PROC OutputOrFail.c (CHAN OF ANY c, 

VAL [jBYTE mess, 
CHAN OF INT kill, 
BOOL aborted) 

This procedure provides, through an abort control channel, for communica- 
tion failure on a channel attempting to output. This is useful if failure cannot 
be detected by a simple timeout. Any integer on the channel kill will 
cause the channel c to be reset and this procedure to terminate. 

Reinitialise 

¥ROC Reinitialise (CHAN OF ANY c) 

This procedure may be used to reinitialize the link channel c a^er it is 
known that all activity on the link has ceased. 

Reinitialise must only be used to reinitialize a link channel after 
communication has finished. If the procedure is applied to a link channel 
which Is being used forcommunication the transputer's error flag will beset 
and subsequent behavior is undefined. 
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1.11 Debugging support library 

Library: debug, lib 

The debugging support library provides four procedures. Two procedures are 
provided to stop a process, one on a specified condition. Tlie third procedure is 
used to insert debugging messages and the fourth procedure is a timer process 
for analyzing deadlocks. 



Procedure 


Parameter Specifiers 


DEBUG. STOP 





DEBUG, ASSERT 


VAL BOOL assertion 


DEBUG. MESSAGE 


VAL []BYTE message 


DEBUG. TIMER 


CHAN OF INT stop 



1,11.1 Procedure definitions 

DEBUG. ASSERT 

PROC DEBUG, ASSERT (VAL BOOL assertion) 

If a condition fails this procedure stops a process and notifies the debugger. 

If assertion evaluates FALSE, DEBUG, ASSERT stops the process and 
sends process data to the debugger. If assertion evaluates true no 
action Is taken. 

If the program is not being run wthin the breakpoint debugger and the 
assertion falls, then the procedure behaves like deibus.STOP. 

DEBUG. MESSAGE 

PROC DEBUG. MESSAGE (VAL []BYTE message) 

This procedure sends a message to the debuggerwhich is displayed along 
with normal program output. Note: that only the first 83 characters of the 
message are displayed. 

If the program is not being run within the breakpoint debugger the proce- 
dure has no effect. 

DEBUG. STOP 

PROC DEBUG. STOP () 

This procedure stops the process and sends process data to the debugger. 

If the program is not being run within the breakpoint debugger then the 
procedure stops the process or processor, depending on the en'or mode 
that the processor is in. 
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DEBUG, TIMER 

PROC DEBUG. TIMER (CHaH OF INT stop) 

A timer process for use when analyzing deadlocks in occam programs. 
The procedure remains on the timerqueue until receipt of any integer value 
on tlie channel stop, whereupon it will terminate. For an example of this 
form of usage see sect'on 9.14.6 rn the User Guide. 

1 .1 2 DOS specific hostio library 

Library: msdos . lib 

The MSDOS host file server library allows programs to use some facilities specific 
to the IBM PC. A set of constant for the library are provided in the include file 

msdos . inc. 

Caution: Programs that use this DOS specific library will not be portable to 
versions of the toolset on other hosts. 



Procedure 


Parameter Specifiers 


dos . receive .block 


CHAN OF SP fs, ts, 

VAL INT32 location, 

INT bytes. read, []B^TE block, 

BYTE result 


dos . send. block 


CHAN OF SP fs, ts, 
VAL IST32 location, 
VAL []BYTE block, 
INT len, BYTE result 


dos . call . interrupt 


CHAN OF SP fs, ts, 
VAL IKT16 interrupt, 
VAL [dos . interrupt . regs . size] BYTE 
register .block . in , 
BYTE carry, flag, 
[dos . interrupt . regs . size] BYTE 
register .block . out , 
BYTE result 


dos . read . regs 


CHAN OF SP fs, ts, 

[dos, read. regs. size] BYTE registers, 
BYTE result 


dos. port. read 


CHAN OF SP fs, ts, 

VAL IKT16 port. location, 

BYTE value, result 


dos . port . write 


CHAN OF SP fs, ts, 

VAL INT16 port. location, 

VAL BYTE value, BYTE result 
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1,12.1 Procedure definitions 

dos . receive .block 

PROC dos, receive. block (CHAN OF SP fa, ts, 

VAL INT32 location, 
IHT bytes. read, 
[IBYTE block, 
BYTE result) 

Reads a block of data, starting at location, from host memory, 
location is arranged as the segment in the top two bytes and the offset 
in the lower two bytes, both unsigned. The number bytes requested is 
SIZE [block] : the number of bytes read is returned in bytes . read. The 
result returned can take any of the following values: 



spr . ok 

spr . bad . packet . size 

tspr . operation , failed 



The read operation was successful. 

Too many bytes were requested to be read: 
{SIZE [block] )> 

doa . max . receive . block . buffer . size. 

The read failed, so bytes .read = 0. If 
result > spr. operation, failed then 
this denotes a server returned failure. (See 
section C.2 in the Toolset Reference 
Manual) 



dos . send . block 



PROC dos. send. block {CHAN OF SP fs, ts, 
VAL INT32 location, 
VAL []BYTE block, 
INT len, BYTE result) 

Writes a block of data to host memory, starting at location. The location 
is arranged as the segment in the top two bytes and the offset in the lower 
two bytes, both unsigned. 

The number of bytes requested to be written is SIZE [block] ; the number 
of bytes written is returned in len. The result returned can take any of the 
following values: 



spr . ok 

spr . bad . packet . size 

>3pr . operation . failed 



The write operation was successful. 

Too many bytes were requested to be 

written: (SIZE [block]) > 

dos . max . send . block , buffer .size. 

The write failed. If result takes a value > 
spr . operation . failed then this 
denotes a server returned failure. (See 
section C.2 in the Toolset Reference 
ManuaL) 
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dos . call . interrupt 

PROC dos . call . interrupt 
(CHAN OF SP fs, ts, 
VAL INT16 interrupt, 

VAL [dos.intarrupt.r«gs.siz«] BYTE register, block. in, 
BYTE carry. flag, 

[dos. interrupt. rega.Bize] BYTE register. block. out^ 
BYTE result) 



Invokes an interrupt call on the host PC, with the processor's registers 
initialized to requested values. On return from the interoipt the values 
stored in the processor's registers are returned in 
register .block, out, along with the value of the carry flag on the PC, 
which is stored in carry. flag. 

The interrupt number is specified by interrupt. The registers are repre- 
sented by a block of bytes called register . block . in. This block stores 
the values to be written to the registers. Each register value occupies 4 
bytes of a block. On the IBM PC the 2 most significant bytes are ignored 
as this machine has only 2 byte registers (16 bit registers). The layout of 
registers in the block is as follows: 



Register 


Start position in block 
(least significant byte) 


End position in block 
(most significant byte) 


£LX 





3 


bx 


4 


7 


cx 


8 


11 


dx 


12 


15 


di 


16 


19 


si 


20 


23 


cs 


24 


27 


ds 


28 


31 


es 


32 


35 


ss 


36 


39 



Note, however, that the cs and ss registers cannot be set. 
The result returned can take any of the following values: 



spr , ok 

>spr . operation . failed 



The interrupt was successful. 

The interrupt failed. If result takes a value 
> spr. operation, failed then this 
denotes a server returned failure. (See 
section 0.2 in the Toolset Reference 
Manual.) 
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1.12 DOS specific hostio library 



dos . read . regs 



PROC dos. read. regs 

(CHAN OF SP fs, ts, 

[dos . read . regs , size] BYTE registers , 

BYTE result) 

Reads the current values of some registers of Uie PC. The values of the 
registers are returned as a block of bytes, each register occupying 4 bytes 
of the block: 



Register 


Start position in block 
(least significant byte) 


End position in block 
(most significant byte) 


ax 





3 


bx 


4 


7 


ex 


8 


11 


dx 


12 


15 



On the IBM PC the 2 most significant bytes are ignored as this machine has 
only 2 byte registers (16 bit registers). 

The result retumed can take any of the following values: 



spr . ok 

^spr . operation . failed 



The read was successful. 

The read failed. If result takes a value > 
spr . operation . failed then this 
denotes a server returned failure. (See 
section C,2 in the Toolset Reference 
ManuaL] 



dos. port. read 



PROC dos. port. read (CHRN OF SP fs, tS; 

VAL INT16 port. location, 
BYTE value, result) 

Reads the value at the port, specified by the port address 
port , location. The port address being in the input/output space of the 
PC is an unsigned number between and 64K. 

No check is made to ensure that the value received from the port (if any) 
is valid. The value returned in value is that of the given address at the 
moment the port is read by the host file server. 

The result retumed can take any of the following values: 
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spr . ok 

^spr . operation . f <iiled 



The read was successful. 

The read failed. If result takes a value > 
spr. operation, failed then this 
denotes a server returned failure. (See 
section C.2 in the Toolset Reference 
Manual.) 



dos . port . write 



PROC dos, port. write (CHAN OF SP fs, ts, 

VAL INT16 port. location f 
VAL BYTE value, BYTE result) 

Writes value to the port specified by the port address port . location. 
The port address being in the input/output space of the PC is an unsigned 
number between and 64K. 

No check is made to ensure that the value written to the port has been 
correctly read by the device connected to the port (if any). 

The result returned can take any of the foilowng values: 



spr . ok 

>$pr . operation , failed 



The write was successful. 

The write failed. If result takes a value > 
spr. operation, failed then this 
denotes a server returned failure. (See 
section C.2 in the Toolset Reference 
Manual.) 
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A Language 
extensions 



This appendix describes language extensions that are supported by the Occam 
2 compiler. 

Note: These extensions are compiler-dependent and do not extend the syntax of 
the Occam 2 language as defined In the Occam 2 Reference Manual. 



A,1 Syntax 

A,1.1 Compiler keywords 

The following additional keywords are supported by the occam 2 compiler: 

ASM GUY IK INLINE VECSPACE WORKSPACE 

A.1 .2 Compiler directives 

The following directives are supported by the Occam 2 compiler 

# INCLUDE #USE #COMMENT # IMPORT #OPTI ON # PRAGMA 
For more information see section 1,12 of the Toolset Reference Manual. 

A.1.3 String escape characters 

The syntax of the non-printable character'*', as defined in section I of the Occam 
2 Reference Manual has been extended. The first character of a literal string may 
now take the value '*1' or '*L', which is used to represent the length of the string, 
excluding the character itsetf. For example, the following statements define the 
same string: 

VAL stringi is "*lFred" : 
VAL string2 is "*#04Fred" : 

'*1' (or'*L') is illegal if the string (excluding the ^*l') is longer than 255 bytes, 
and will be reported as an error, 
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A.2 Channel operations 


The characters * 


^ ' and 


" may be used in the following form: 






*c 


*C 


carriage return 


= 


*#0D 






*1 


*L 


string length 


< 


*#FF 






*n 


*N 


newline 


= 


*#0A 






*t 


*T 


tab 


= 


*#08 






*s 


*S 


space 


= 


*#20 






*/ 




quotation mark 










*fr 




double quotation mark 










■k* 




asterisk 









Any byte value can be represented by "*# followed by two hexadecimal digits. 

A.1.4 Tabs 

• The compiler expands tabs in source files to be every eighth character 
position. Tabs are permitted anywhere In a line but are not expanded within 
strings or character constants. 

A.1.5 Relaxations on syntax 

• There is no limit on the number of significant characters in identifiers, and 
the case of characters is significant. 

A.2 Channel operations 

The following operations on channels are now permitted: 

• Channels can be retyped 

• Channels can be constructed from other channels ('channel constructors') 

• Protocols of type AKY can be named {'anarchic protocols') 

A.2.1 Retyping channels 

Channels may be retyped: 

• to and from data items 

• between protocols of different types. 

Data items map onto a pointer to the channel word. This tan be used, for example, 
to detennine the address of the channel word, or to create an an-ay of channels 
pointing at particular addresses: 

CHAN OF protocol c : 

VAL INT X RETYPES c ; — Must be a VAL RETYPE 
use X as the address of the chaiuiel word 
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Note; This operation (retyping a cliannel to a data item) can be achieved more 
portably by means of tlie LOAD , INPUT . CHANKEL predefine. See sections 13,4 of 
the Occam 2 Toolset User Guide and 1.37 in this manual. 

The following code demonstrates how to create a channel array whose channels 
point at arbitrary addresses. 

110] INT X : 
SEQ 

initialise elements of x to the addresses of 

the channel words 
[10] CHAN OF protocol c RETYPES at : 

use channel array c 

Retyping between channel protocols allows the protocol on a channel lo be 
changed, for example, in order to pass it as a parameter to another routine: 

PROTOCOL PROT32 IS INT32 : 
PROC p {CHAN OF INT32 x) 
X ? 99(INT32} 

PROC ql (CHAN OF PROT32 y) 
SEQ 

p (y) — this is illegal 

CHAN OF INT32 z RETYPES y : 

p (7) — this is legal 



This facility should be used with care; further details are given in section 13.2 of 
the Occam 2 Toolset User Guide, 

A.2.2 Channel constructors 

An-ays of channels may be constnjcted out of a list of other channels, see section 
13.2 of the Occam 2 Toolset User Guide. For example: 

PROC p (CHAN OF protocol a, [2] CHAN OF protocol b) 
[3]CHAN OF protocol c IS [a, b[0] , b[l]] : 

— channel constructor 
ALT i = FOR SIZE C 
c[i] ? data 



A.2.3 'Anarchic' protocols 

PROTOCOLS may now be declared of type any. This means that a channel of that 
protocol can communicate a single item of any type. Sequential protocols can 
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include an item of type any. This suppresses type-checking of a single element in 
a communication lisL Note that these should be contrasted against CHAN OF 
ANY, where the Iteyword ANY matches any number of items. 

The following addition is made to the occam syntax in the Occam 2 Reference 
Manual: 

simple.pmtocol - any 

For example: 

PROTOCOL pO IS ANY : 
CHAN OF pO cO : 
SEQ 

cO r 88 

eO r 'b' 

cO » 6 : : "heaven" 

PROTOCOL pi IS INT ; ANY : 

CHAN OF pi cl : 

SEQ 

cl ? 0; 88 

cl r 1; 'b' 

cl ! 2 ; 6 : : "heaven" 

Note: CHAN OF ANY is now considered obsolescent and the named protocol 
construct described above should be used in preference. 

CHAN OF ANY 

The facility which allows a channel declared as Chan OF any can be passed as 
an actual parameter in place of a fomiai channel parameter of any protocol is still 
supported but is obsolescent. A channel of a specific protocol cannot be passed 
in place of a fomfiai channel parameter of CHAN of any. Communications on a 
channel declared as CHAN of any must be identical at both ends of the channel. 



A.3 Low level programming 

A.3.1 ASM 

The keywond ASM introduces a section of transputer assembly code. See appendix 
D of the Occam 2 Toolset User Guide. 

A.3.2 PLACE statements 

The PLACE statement in occann allows a channel, a variable, an an-ay, or a input/ 
output channel for a memory mapped device (port), to be placed at an absolute 
location in memory, workspace, or vector space. 
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The syntax of the supported PLACE statements extends the definition of an alloca- 
tion as defined in the Occam 2 Reference Manual: 

allocation = PLACE name AT expression 

I PLACE name AT WORKSPACE express/on 

I PLACE name IN WORKSPACE 

I PLACE name IN VECSPACE 

The PLACE statement must be inserted immedtateiy following the declaration of 
the variable to which it refers e.g. 

int X, y, z ; 

PLACE X 

PLACE y is correct 

int X : 

int y ; 

PLACE X is incon-ect 

The address used in a place aliocation is converted to a transputer address by 
considering the address to be a word offset from moStneg INT. 

For example, in order to access a BYTE memory mapped peripheral located at 
machine address #1234, on a 32-btt processor: 

PORT OF BYTE peripheral : 

PLACE peripheral AT (#1234 X (MOSTNEG INT)) » 2 : 

peripheral ! (BYTE) 

The numbers used as PLACE addresses are word offsets from the bottom of 
address space. For example, PLACE scalar channel 3iT n places the channel word 
at ^at address, and PLACE array of channels AT n, places the an-ay of pointers 
at that address. 

The PLACE name IN workspace and place name in vecspace statements 
place variables explicitly in program workspace and vector space respectively. 
The aliocation of workspace and vectorspace by the compiler is described in 
Appendix B of this manual. Section 13.1 of the Occam 2 Toolset User Guide also 
describes allocaUon. 



A,3*3 INLINE keyword 

INLINE may be used immediately before the PROC or fonct ion keyword of any 
procedure or function declaration. It witl cause the body of the procedure or func- 
tion to be expanded Inline in any call, and the declaration will not be compiled as 
a normal routine. Use of inline procedures or functions may increase the size 
of the object module but will also avoid the overheads incurred in executing extra 
calls. 
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The INLINE statement extends the syntax ofa definition as defined in the OCCBfT) 
2 Reference Manual: 

definition = reoTOCOL name IS simple.protocol: 

I PROTOCOL name is sequential.protocol: 
I KiOTOCOL name 

CASE 

{tagged.pmtocofi 

I [ INLINE] PROC name ( fo , formal ] ) 
procedure.body 

I {f , primitive type } [INLINE] function name 
( fo , format)) function.tx>dy 

1 {j , primitive type } [INLINE] FUNCTION name 

( t) , formal } } IS expression.lisi: 
I specifier name retypes element: 
I VAL specifier name retypes expression: 

Exannples: 

INT XNI.X11E ftJNCTION aum3 [VAL INT x, y, z,] IS x + (y + z} : 

INLINE PROC seterror [} 
ftrror := tkujc 

A call to the function sum3: 

so, write, intCfSr ts, sum3(p,q,r) ,0} 

would be expanded by the compiler thus: 

so.write.int(fs, ts, p + (q + r) ,0) 

Note: the declaration is marked with the keyword, but the call is affected. This 
means that you cannot inline expand procedures and functions which have been 
declared by a #USE directive; to achieve that effect you may put the source of the 
routine, marked with the INLINE keyword, in a separate file, and include this file 
with an #INCLUDE directive, 

A-4 Counted array input 

The semantics of counted array input are extended from those described in the 
Occam 2 Reference Manual. 
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The new semantics are as follows: 

message ? len : : buffer 

This input receives an integer value which is assigned to the variable len, and that 
number of components, which are assigned to the first components of the anay 
buffer. The assignments to len and buffer happen in parallel and therefore 
the same rules apply as for parallel assignment. That is, the name len may not 
appear free in buffer, and vice versa. 

In Occam 2 the count was input first and the parallel assignment rules did not 
apply. Some occam 2 programs are invalidated by the new rule. 

As a concession to backwards compatibility, the compiler permits communications 
of the form: 

channei.exp ? name : : [ array.exp FROM o for name ] 

These are transformed by the compiler into the equivalent modem form: 

channei.exp ? name : : array.exp 

A.5 Retyping arrays 

Multi-dimensional an"ays defined by a retypes definition may have one element 
whose value is not explicitly stated. This may be any one of the elements. For 
example: 

[6] INT a, f : 

[2] [ ]INT b RETYPES a : 
[ 1 [3] INT c RETYPES f : 

[24]IKT d : 

12] [ ] [6] e RETYPES d : 

A.6 Obsolescent features 

The following language constructs are considered to be obsolescent, and may be 
removed In future versions of the compiler: 

• CHAN OF ANY as defined in the Occam 2 Reference Manual Is obsoles- 
cent. It should be replaced by a named PROTOCOL (which may be of type 
ANY), to give greater security. Any declaration of a channel of type CHAN 
OF ANY will be flagged by a warning by the compiler. 

• The language extension which provides the ability to pass an actual 
parameter of type CHAN OF ANY to a procedure whose formal parameter 
Is of a different channel type is obsolescent. Channel RETYPE should be 
used to make the type conversion explicit. 
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* The ability to write the following counted array input is obsolescent 
channei.exp ? name : : [ array.exp from o tor name ] 

The following equivalent constmct should be used Instead. 
channel.exp ? name : : array.exp 

• The GUY construct is obsolescent; the asm construct should be used 
instead. 
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B Implementation of 
Occam on the 
transputer 



This appendix defines the toolset implementation of Occam on the transputer. It 
describes how the compiler allocates memory and gives details of type mapping, 
hardware dependencies and language. The appendix ends with the syntax defini- 
tion of the language extensions implemented by the occam compiler. 



B.1 Memory allocation by the compiler 

The code for a wdiole program occupies a contiguous section of memory. When a 
program is loaded onto a transputer in a network, memory is allocated in the 
following order starting at MemStart: workspace; code; separate vector space. 
This Is shown below: 



Higher address 

1 
Lower address 

MemStart -h> 






Free memory 




Vector space 


Code 


Workspace 









B.1.1 Procedure code 

The compiler places the code for any nested procedures at higher addresses 
(nearer mostpos int) than the code for the enclosing procedure. Nested proce- 
dures are placed at increasingly lower addresses in the order in which their defini- 
tions are completed. For the code in the following example: 
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B.I Memory allocation by the compiler 



PROC P() 
PROC Q 

code for Q 

PROC R 

code for R 

code for P 



the layout of the code in memory 


\S\ 




HOSTPOS INT 
\ 

Higher address 

Lower address 

MOSTNEG INT 






Code for Q 




Code for R 


Code for P 







B.1.2 Compilation modules 

The order in which compilation modules are placed in memory, including those 
referenced by a #pragma linkage directive, is controlled by a linker directive. 
Modules are placed in priority order, with the highest priority module being placed 
at the lowest available address. 

Note: the compiler will attempt to optimize floating point routines such as 
REAL320P and REAL320PERR by giving them a high priority. This can be over- 
ridden by using the compiler directive #PRAGMA linkage in conjunction with the 
linker directive #section. 

B.I .3 Workspace 

Workspace is placed lowest In memory, before the arithmetic handling library, so 
that it has priority usage of tiie on-chip RAM, If the processor is configured to have 
any 

Woricspace is allocated from higher to lower address (i,e. the wori<space for a 
called procedure is nearer MOSTNEG INT than the woritspace for the caller). For 

example: 
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PROC P 





, , , 


code 


here 






code 


PROC Q 


{) 


P 





In the above example when Q is called, it will in turn call P. At the point labelled 
her«, the data layout in memory will be: 



Higher address 



Lower address 



Workspace for Q 



Workspace for P 



In a FAR or PRi PAR construct the last taxtually defined process is allocated the 
lowest addressed workspace. For example: 

FAR 

.,, PI 
,., P2 
,.. P3 

the workspace layout for the parallel processes will be: 









Higher address 

1 nwpr firidrp^^ 


Workspace for P1 




Workspace for P2 


Wori(space for P3 









In a replicated PAR construct the instance with the highest replication count is allo- 
cated the lowest workspace address. For example: 

PAR i = FOR 3 
P [i] 
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B,1 Memory allocation by the compiler 



the workspace layout for the parallel processes will be: 









Higher address 
Lower address 


Workspace for PIO] 




Workspace for P[1] 


Workspace for P[2I 







Unless separate vector space is disabled, most arrays are allocated in a separate 
data space, known as vector space, see section B.I A. The allocation is done in 
a similar way to the allocation of workspace, except that the data space for a called 
procedure is at a higher address than the data space of its caller. 

The variables within a single procedure or parallel process are allocated on the 
basis of their estimated usage. The variables which the compiler estimates will be 
used the most, are allocated tower addresses in the current workspace. 

From within a called procedure the parameters appear immediately above the 
local variables. When an unsized vector is declared as a formal procedure param- 
eter an extra val int parameter is also allocated to store the size of the aray 
passed as the actual parameter This size is the number of elements in the an^ay. 
One extra parameter is supplied for each dimension of the an'ay unsized in the call, 
in the order in which they appear in the declaration. 

If a procedure requires separate vector space, it is supplied by the calling proce- 
dure, A pointer to the vector space supplied is given as an additional parameter. 
If the procedure is at the outer level of a compilation unit, the vedor space pointer 
is supplied after all the actual parameters. Otherwise it Is supplied before all the 
actual parameters. 

B.I. 4 Vectorspace 

By default, aaays larger than 8 bytes are allocated into a separate stack known as 
the vectorspace. This scheme optimizes use of the workspace, creating more 
compact and quicker code. It can also make better use of a transputer's on-chip 
RAM. The default scheme may be overridden by an option on the command line, 
a directive in the source code, or, for specific variables only, by a place statement. 

This can be ovenidden per compilation unit by the V command line switch or 
#OPTION "V" directive. This will force all variables into the workspace. 
Secondly, the current 'default' may be overridden on an array-by-an^y basis by 
using extra allocations as follows: 
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[100]BYTE a : 

PIACE a IN HORKSPACE 

workspace 

[100] BYTE b : 

PLACE b IN VECSPACE ; 

vector space 



forces a to reside in 



forces b to reside in 



Only an^ays may be placed in vectorspace; scalar variables must reside in work- 
space. Arrays smaller than 8 bytes may be explicitly placed in vectorspace. 

It may be desirable to change the default vectorspace allocation for various 
reasons. Using vectorspace can actually slow down execution, since an extra 
parameter is passed to each subroutine which requires it. However, this cost is 
normally ovenvhelmed by the reduction in workspace size, and the associated 
compaction in the number of prefix instmctlons required to address local variables. 
In certain circumstances it may be useful to place a commonly used aray into 
workspace, particularly If it is heavily used in an^ay assignment (block moves), 
Altematively it may be useful to place most an^ays in workspace, but move any 
large arrays into vectorspace. 



B.2 Type mapping 

This section defines all the Occam types and how they are represented on the 
each target processor. 

All objects are word aligned, i,e. the lowest byte of the object is on a word boundary. 
For objects of type BOOL and BYTE, the padding above the object is guaranteed 
to be all bits zero: for all other objects, the value of any padding bytes is undefined. 

Arrays are packed, i.e. there are no spaces between the elements. (Note: that an 
object of type BOOL has one byte for each element). 

Table A,1 summarizes the type mapping, for further information on data types see 
Section 3 of the occam 2 Reference Manual. 

Protocol tags are represented by 8-bit values. The compiler allocates tag values 
for each protocol from (BYTE) upwards in order of declaration. 

Values accessed through retypes must be aligned to the natural alignment for 
that data type; bytes and bools may be aligned to any byte; iNT16s on a 32 bit 
processor must be aligned to a half-word boundary and all other data types must 
be aligned to a word boundary. This will be checked at run-time if it cannot be 
checked at compile time. For example: 
[20] BYTE array: — This will be word aligned 



XNT32 X RETYPES [array FROl 1 FOR 4] 
INT32 y RETYPES [array FROU i rOR A] 
INT32 z RETYPES [array FRC»1 S FOR 4] 



— Run-tlmft check is inserted 

— Run-time check is inserted 

— No run-tixM check inverted 
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B,3 Implementation of channels 



Channels may beRETYPEd. This allows the protocol on a channel to be changed, 
in order to pass it as a parameter to another routine. This facility should be used 
with care, see section A.2.1 . 



Type 


Storage 


Range of values 


BOOL 
BYTE 


1 byte 
1 byte 


FALSE, TRUE 
to 255 


INT16 
INT32 
INT64 


2 bytes 
4 bytes 
8 bytes 


-32768 to 32767 
-2,147,483,648 to 2,147.483,647 
-263 to (263-1) 


INT (On 32-bit processors) 


4 bytes 


-2,147,483,648 to 2,147,483,647 


INT (On 16-bit processors) 


2 bytes 


"32768 to 32767 


REAL32 
KKAL64 


4 bytes 
8 bytes 


IEEE single precision format 
IEEE double precision format 


CHAN (On 32-bit processors) 


8 bytes 


Channels are implemented as a 
pointer to a channel word. 


CHAN (On 16"bit processors) 


4 bytes 


PORT OF D 


AsforD 




TIMER 


None 





Table A.1 occann data types 

B.3 Implementation of channels 

The data type of a channel is 'pointer to channel . When mapping channels to 
specific transputer links, the channel word is placed at the specified address for 
scalar channels. An^ys of channels are mapped as arrays of pointers to channels. 

As a result of this PLACE ing an^ys of channels is implemented such that: 

PLACE array. of .channels AT n: 
places the an'ay of pointers at that address. 

PLACE scalar. channel AT n: 

places the channel word at that address. 

An example of the placement of channels on links is given in Chapter 13 of the User 

Guide. 

An-ays of channels may be constructed out of a list of other channels. For example : 
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PROC p (CHAN OF protocol a, 12] CHAN OF protocol b) 
[3]CHAN OF protocol c IS [a, b[0] , b[l]] i 
— channel constructor 

ALT i = FOR SIZE c 
di] ? data 



Channel constructors extend the facilities for manipulating channels; further 
mformation is given In section 13.2 of the User Guide. 



B.4 Transputer timers (clocks) 

The transputer has two timers which can be accessed by the programmer. They 
are used for real time programming, timing events, data logging, timing out, delays 
and so on. 

Two timers are provided to give [ow and high resolution timing. The timers them- 
selves are word length registers which are incremented regularly and related to the 
speed of the input clock. The low resolution timer goes 64 times slower than the 
high resolution timer. These speeds are independent of transputer model, 
processor speed, and word length. 



Priority 


Low 


High 


Time between ticks 


64^ 


Ins 


Ticks per sec 


15625 


1000000 


Approx. cycle time (16 bit) 


4s 


65ms 


Approx. cycle time (32 bit) 


76h 


1h10m 



The high resolution timer is always used by high priority processes, so is often 
called the high priority timer The low resolution timer is always used by low priority 
processes. 

B.4.1 TIMER variables 

TIMER variables in Occam give access to the transputer timers. The syntax of 
timer input is similar to channel input. 

Timers can have only one of two possible values, con-esponding to the high and 
low priority transputer docks. The clock which is read depends on the priority of 
the enclosing process. When comparing clock values the same timer variable 
should be used, and the value must be input from the same process or from a 
process of the same priority. If the same timer is used in processes with different 
priorities, the results are undefined. 

A common use of timers is to time a process, for example, a channel input: 
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TIMER clock; 
SEQ 

clock ? start 

chan ? y 

clock ? end 

delay := «nd MINUS start 

The MINUS operator performs a 'modulo' subtraction and is used to give a relative 
difference because the transputer timers operate on a wrap-around principle. Ttie 
maximum period tiiat can be timed is limited to clock-cycle-time divided by 2 i.e. 
on 1 6 bit transputers, about 33ms at high priority and 2s at low priority. If the period 
being measured is tikely to be greatertJian this then a delay period based on multi- 
ples of clock cycles should be built in. 

B.4.2 TIMERS as formal parameters 

When calling Occam from C, any formal timer parameter in the occam proce- 
dure or function must be ignored by the calling C code, and no actual parameter 
should be passed. When calling Occam routines from other occam n^utines an 
actual parameter should be passed In the normal way. 

B.5 CASE statement 

The CASE statement is implemented as a combination of explicit test, binary 
searches, and jump tables, depending on the relative density of the selection 
values. The choice has been made to optimize the general case where each selec- 
tion is equally probable. The compiler does not make any use of the order of the 
selections as they are written in the source code. 

B.6 ALT statement 

No assumption can be made about the relative priority of the guards of an ALT 
statement; if priority is required, you must use a PRI ALT. 



B J Formal parameters 

[fa name is used more than once in a single formal parameter list, the last definition 
is used. 



B.8 Hardware dependencies 

• The number of priorities supported by the transputer is 2, (i.e. high and 
low), so a PRI PAR may have two component processes. The compiler 
does not permit a PRI par statement to be nested inside the high priority 
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branch of another. This is checked at compile time, even across separately 
compiled units. 

The low priority cloclc increments at a rate of 15 625 ticks per second, or 
one yck = 64 microseconds (IIVIS T212, T222, T225, M212, T400, T414, 
T425, T800, T801 and T805), 

The high priority dock increments at a rate of 1 000 000 ticks per second, 
or one tick = 1 microsecond (IMS T212, T222, T225, M212, T400, T414, 
T425, T800, T801 and T805). 

TIMER channels cannot be placed In memory vwth a PLACE statement. 



B.9 Summary of implementation restrictions 

• FUNCTIONS may not return arrays, not even with fixed sizes. 

• Multiple assignment of anays of unknown size is not pem^itted. 

• Replicated PAR count must be constant. 

• There must be exactly two branches in a PRI par. 
« Replicated FRI pars are not permitted. 

• Nested PRI PARS are not permitted. 

• PLACE statements must immediately follow the declaration of the variable 
to which they refer 

• Compiler pragmas SHARED and PERMITALIASES must immediately 
follow the declaration of the variable to which they refer. 

• Table sizes must be known at compile time, for example: 

PROC p {[IINT a, E]INT b) 
VAL [] []INT X IS [a] ; — this is illegal 
VAL E]INT y IS b : — this is legal 

• Constant arrays which are indexed by replicator variables are not consid- 
ered to be constants for the purposes of compiler constant folding, even if 
the start and limit of the replicator are also constant. This restriction does 
not apply during usage checking. 

• FUNCTIONS which use ALT replicator variables as free variables may not 
be called in the guard of the same ALT. An en-or is reported at compile time 
if this occurs. Example: 
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PROC P{[10]CHAN OF INT c 
ALT i = FOR 10 

IKT FDNCTION f () IS 9 - i : 
INT x: 

c[f ()] ? X ~ call of ^f()' is illegal 
SEQ 

ALT 

c[f()] ? X — this is legal. 

This can be resolved by passing the replicator variable into the function 
as a parameter: 

PROC PC [10] CHAN OF INT c 
ALT i = FOR 10 

INT FUNCTION f (VAL INT i) IS 9 - i : 
INT x: 

c[f(i)] ? X — call of 'f(i)' is legal 
SKIP 

• Maximum array size is 64 Kbytes on 16-bit processors, 2 Gbytes on 32-bit 
processors. No dimension of any array may exceed M0STP05 INT. 

• Maximum filename length is 128 characters. 

• Maximum 256 tags ailowed in PROTOCOLS, 

• Maximum number of lexical levels is 254. (Applies to nested PROCs and 
replicated pars), 

• The compiler places restrictions on the syntax which is permitted at the 
outenrtost level of a compilation unit; i.e. not enclosed by any function or 
procedure. 

- No variable declarations are permitted. 

- No abbreviations containing function calls orvALOFs are allowed, even 
if they are actually constant. For example: 

VAL X IS (VALOF 

SKIP 

result 99 
) ; — This is illegal. 

VAL m IS max (27^ 52) : — This is also illegal. 
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C.1 Alias checking 

This section describes the alias checking that is implemented by the compiler. 
In the following text 'assigned to' means 'assigned to by assignment or input'. 

C.1.1 Introduction 

Alias checking is the name given to the series of checks made by the compiler on 
Occam 'abbreviations' to ensure that an object is known by a single name within 
a given scope i.e. no "aliases' exist. In practice this means that: 

• named abbreviations must be used correctly within the code 

• expressions used to define abbreviations (plus any subscripts within them) 
must be valid and within range 

• variables in defining expressions must not be changed. 

The same rules apply to retyped names, since retyping is simply another fonn of 
abbreviation. 

Alias checking is governed by a strict set of rules. This enables many checks to be 
done at compile time, redudng the need for runtime checking code. Some checks, 
however, can only be performed at runtime. 

Alias checking can be disabled in a compilation unit or for specific variables. It is 
then up to the programmer to ensure that the rules are complied with, or the 
behavior of the program is undefined. 

The formal rules for alias checking are set out below. For further details see the 
Occam 2 Reference ManuaL 

C.1.2 Rules 

Scalar variables 

(Rule 1) If a scalar variable appears in the abbreviated expression of a VAL 
abbreviation, for example: 

X in VAL a IS X + 2 : 
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then that variable may not be assigned to or abbreviated by a non-VAL abbrevi* 
atfon anywhere within the scope of the VAL abbreviation. 

(Rule 2) If a scalar variable is abbreviated in a non-VAL abbreviation, for example: 

X in a IS X : 

then that variable may not be referenced anywhere within the scope of the abbrevi- 
ation. 

Arrays 

The rules for arrays attempt to treat each element of the array as an individual 
scalar variable. They allow the maximum freedom possible without introducing run 
time checking code except at points of abbreviation. In the following text the word 
constant means any expression that can be evaluated at compile time. If an array 
is referenced in the expression of a VAL abbreviation, for example: 

X InVAL a IS x[i] : 

then the follo\Mng rules apply to the use of the array within the scope of the abbrevi- 
ation: 

(Rule 3) If the subscript is constant then elements of the array may b^ 
assigned to as long as they are only subscripted by constant values 
different from the abbreviated subscript Any element of the array may also 
appear anywhere in the expression of a VAL abbreviation. Any other 
elements of the an*ay may be non-VAL abbreviated, and run time checking 
code is generated if subscripts used in the abbreviation are not constant. 

(Rule 4) If the subscript Is not constant then no element of the an^y may 
be assigned to unless it is first non-VAL abbreviated. The non-VAL abbrevi- 
ation will have to generate run time code to check that it does not overlap 
the VAL abbreviation. The array may be used in the expression of a VAL 
abbreviation. 

Elements of the array may be accessed anywhere within the scope of the 
abbreviation except ^^ere restricted by further abbreviations. If an an-ay 
is abbreviated in a non-VAL abbreviation, for example: 

X ina IS x[i] : 

then the following rules apply to the use of the array within the scope of the 
abbreviation: 

(Rule 5) If the subsaipt is constant then elements of the an^y may be read 
and assigned to as long as they are accessed by constant subscripts 
different from the abbreviated subscript. Other elements of the an-ay may 
be abbreviated in further val and non-VAL abbreviations, and run time 
checking code is generated if subscripts used in the abbreviation are not 
constants. 
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{Rule 6) If the subscript is not constant then the array may not be refer- 
enced at all except in abbreviations where run time chedting code is 
needed to checit that the abbreviations do not overlap. 

(Rule 7) Variables used in subscripts of the an^y being abbreviated act as 
if they have been VAL abbreviated. In the above example V acts as if it has 
been val abbreviated and cannot be altered in the scope of the abbrevi- 
ation. Where elements of the array being abbreviated are used in the 
subscript of the array then the abbreviation is checl<ed as If the subscript 
expression was VAL abbreviated just before the non-VAL abbreviation. For 
example: 

a IS x[x[2]l : 

is checked as if it was written: 

VAL subscript IS x[21 : 
a IS X [subscript] : 

which (by Rule 6 above) vwll generate run time checking code. 



C.1.3 Alias checking disabled 

Note: the compiier will be able to generate the most efficient code when all alias 
checks are enabled. 

When alias checking is disabled, either on a compilation unit or on specific vari- 
ables, the compiler cannot guarantee no aliasing on the affected variables. It is 
then the programmer's responsibility to ensure that the following rules are not 
broken. 

The set of 'aliasable' variables consists of either the set of a// variables declared 
in the compilation unit (If the whole compilation unit has alias checking turned off 
by the 'A' command line option orthe#OPTlON "A" directive), or the set of all vari- 
ables which have been marited by the pragma PERMITALIASES. See chapter 1 
in the Toolset Reference Manual. 

In the presence of *aliasable' variables, the behavior of a program is defined in the 
intuitive model, where all reads and assignments to 'aliasable' variables are 
executed strictly in the order in which they are written; they may not be re-ordered 
by an optimizer. Note also that because of retyping it cannot be assumed that a 
write to an 'aliasable' variable of one type will not affect an 'aliasable' variable of 
another type. 

When variables are 'aliasable' the following mles apply. 

VAL abbreviations 

Suppose we have a VAL abbreviation of the form: 
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VAL name is expression : 
If name is 'aliasable', then 

all component variables of expression are automatically Inferred to be 
'aliasable' by the compiler and may be modified in the scope of the abbrevi- 
ation, 

and therefore: 

name must not be used after any component variable of expression Is 
modified. 

If this constraint is not met, the behavior of the program is undefined, and results 
will be implementation-dependent. 

For example: 

V%L X IS a[i] : 
fPR&GHA PEBHITALIASES x 
SEQ 

- . . use 'x' — This is OK 

... modify U' or 'ali]' — This is OK if ^x' is 

~ ^aliasable' 
use ^x' — This is undefined 

Non-VAL abbrevlaUons 

Suppose we have a non-VAL abbreviation of the form: 

name is element : 
If name is 'aliasable', then: 

any variable used in a subscript to select a component or components of 
an an^y reference in element may be modified in the scope of the abbrevi- 
ation. (All such variables are automatically inferred to be 'aliasable' by the 
compiler.) 

and therefore: 

name must not be used after a variable used in a subscript to select a 
component or components of an array referenced in element has been 
modified. 

If this constraint is not met, the behavior of the program is undefined, and results 
will be implementation-dependent. 

If the base variable of element is 'aliasable' then: 

the actual element referred to by such an abbreviation may be modified 
within the scope of the abbrewation. name is automatically infen'ed to be 
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'aliasab^e' by the compiler, and the abbreviation is implemented as thougii 
name is a pointer to the element. 

An alias may subsequently be created, either by refemng to element explicitly in 
the scope of the abbreviation, or by using another abbreviation within the scope. 

Multiple assignment 

In a multiple assignment, the destinations of the assignment are written to as 
though they are in parallel. Therefore: 

variables listed as the left hand side of a multiple assignment must not be 
aliased. 

It is up to the programmer to ensure that this rule is complied wth. If it is not, the 
behavior of the program is undefined. 

Note that it is perfectly legal for the destinations of an assignment to alias expres- 
sions used on the right hand side of an assignment. Thus destination variables may 
be aliased with actual parameters to a function. 

Procedure parameters 

It is assumed that only (non-VAL) fonnaf parameters of a procedure which are 
'aliasable' may be aliased, either with each other, with the VAL parameters, or with 
'aliasable' free variables. 

If an actual parameter to a procedure aliases another actual parameter, or aliases 
a tree variable used by the procedure, then: 

the fomiat parameter must be marked as 'aliasable'. Note that this also 
applies across separately compiled units. 

Since the rules for procedure parameters derive from those for abbreviations, the 
following constraint applying to val abbreviations also applies. That is: 

any variable used In an actual parameter corresponding to a val formal 
parameter must not be modified in the body of the procedure prior to the 
final read of the formal parameter. 

It is up to the programmer to ensure that these mies are complied with. If they are 
not, the behavior of the program is undefined. 

Interaction with usage checking 

Since the usage checking algorithms rely on lack of aliasing, any 'aliasable' vari- 
able is automatically Inferred to be 'shared', see section C.2.8, 

C.2 Usage checking 

This section describes the usage checking that is implemented by the compiler. 
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C.2.1 Introduction 

Usage checking Is the name given to the series of checks made by the compiler 
to ensure that parallel processes do not share variables, channels span only two 
processes, and communication down channels is unidirectional. Using a set of 
rules means that many checks can be done at compile time^ reducing the need for 
runtime checking code. 

C.2.2 Usage rules of Occam 

The usage checking rules of Occam 2 are as follows: 

• No variable assigned to, or input to, in any component of a parallel may be 
used in any other component. 

• No channel may be used for input in more than one component process 
of a parallel. 

• No channel may be used for output in more than one component of a 
parallel, 

• A variable which is named on the right hand side of a non-VM. abbreviation 
is considered to be modified, whether or not it actually is. 

• Formal array parameters of a routine are considered to be wholly accessed 
if any component of the array is accessed, whether or not by a constant 
subscript. Similariy, free arrays (i.e. an'ays which are accessed non-locally) 
of any routine are also considered to be wholly accessed if any component 
of the array is accessed. 

C.2<3 Checking of non-array elements 

Variables and channels which are not elements of arrays are checked according 
to the rules of Occam Z 



C«2.4 Checking of arrays of variables and channels 

Where possible, the compiler treats each element of an an-ay as an independent 
variable. This makes it possible to assign to the first and second elements of an 
array in parallel. 

For usage checking to operate in this way, it must be possible for the compiler to 
evaluate all possible subscript values of an array. The compiler is capable of 
evaluating expressions consisting entirely of constant values and operators (but 
not function calls). Where a replicator is used in an expression the compiler can 
evaluate the expression for all values of the index provided that the replicator's 
base and count can be evaluated. Note: however, that as each iteration of the 
routine is checked, this can slow the compiler down. 
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Where an array subscript contains variables, a function call, or the index of a repli- 
cator where the base orthe count cannot be evaluated, the compiler assumes that 
all possible subscripts of the array may be used. This may cause a spurious error. 
For example, consider the following program fragment 

X := 1 

PAR 

a[0] := 1 
a[x] ;= 2 

The compiler reports the assignmenttoa[x] as a usage error. The fragment could 
be changed to: 

VAL X IS 1; 

PAR 

a[0] ;= 1 
a[x] := 2 

This would be accepted by the compiler because x can be evaluated at compile 
time. 

The compiler checks segments of arrays similarly to simple subscripts. Where the 
base and count of a segment can be evaluated, each segment is treated as though 
it has been used individually Where the base or count cannot be evaluated, the 
compiler behaves as if the whole an'ay has been used. For example, the following 
code is accepted without generating an error 

FAR 

[a FROM 4 FOR 4] :=: x 

a[8] := 2 

[a FROM 9 FOR 3J := y 

C.2.5 Arrays as procedure parameters 

Any variable an-ay which is the parameter of a procedure is treated as a single 
entity. That is, if any element of the array is referenced, the compiler treats the 
whole an-ay as being referenced. Similariy, if any variable an-ay, or element of a 
variable an'ay is used free in a procedure then the compiler treats it as if every 
element were used. For example, the compiler reports an en^or in the following 
code because it considers every element of a to have been used when p (a) 
occurred. 

PROG p(I]INT a) 
a[ll := 2 

PAR 
P(a) 
alO] := 2 
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Similarfy, where one element of an an^y of channels is used for input or output 
within a procedure, the compiler treats the an^ay as if all elements were used in the 
same way. For example, the compiler reports an error in the following code 
because it considers an output has been performed on every element of c when 
p() occurred. 

ROC p() 

— c free in p 



EROC p() 
e[ll ! 


2 


PAR 

P() 

c[0] t 


1 



C.2.6 Abbreviating variables and channels 

The compiler treats an element which is abbreviated in an element abbreviation 
as if it had been assigned to, whether or not it is actually updated. If this causes 
an apparently con-ect program to be rejected the program should be altered to use 
a VAL abbreviation. For example, the compiler reports an error in the following 
code because it considers the first component of the PAR to have been assigned 
tob. 



PAR 






a 


IS b I 




X 


:= a 




y 


:= b 




le changed to: 




PAR 






VAL a IS 


b 


X 


:= a 




y 


:= b 





Where a channel is an abbreviation of a channel array element, the compiler 
behaves as if the whole of the channel an-ay had been used unless the element 
is an array elei^ent with constant subscripts, a constant segment of an an-ay (i.e. 
with constant base and count) or a constant segment with constant subscripte, 

C.27 Channels 

A channel formal parameter, ora free channel of a procedure, may not be used for 
both input and output in a procedure. This check is disabled if usage checking is 
disabled. 

C.2.8 Usage checking disabled 

Note: the compiler will be able to generate the most efficient code when all usage 
checks are enabled. 
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The compiler supports two switches which can be used to disable either Usage 
checking only, or both Alias and Usage checking together. Usage checking can be 
disabled on a compilation unit by the "N' command line switch or argument to the 
#0PTI0N compiler directive. Usage checking can also be turned off on specific 
variables using the SHARED pragma. See chapter 1 in the Toolset Reference 
Manual for more details. 

When usage checking is disabled it is the programmer's responsibility to ensure 
that variables and channels are used correctly according to certain rules, if they 
are not the behavior of the program Is undefined. 

The set of 'shared' variables consists of either the set of all variables declared in 
the compilation unit, if the whole compilation unit has usage checking disabled, or 
the set of all variables which have been marked by the pragma shared. 

The effects of disabling usage checking are best defined by what happens at a 
synchronization point - a point where the relative progress of hvo processes is 
known. A synchronization point Is defined to be one of the following: 

• A communication (on a channel, timer, or port) 

• The beginning or end of a PAR constmd. 

A program using shared variables is valid provided that: 

• If between hvo synchronization points of a process, a process reads a 
shared variable, then the variable is not updated by any other process at 
any time between these two points. 

(This means that an implementation is at liberty to read the shared variable 
from memory after the first synchronization point, and then to 'cache' a 
local copy of the variable, if it wishes.) 

• If between two synchronization points of a process, a process updates a 
shared variable, then the variable is neither read nor updated by any other 
process at any time between these two points. 

{This means that an implementation is at liberty to read the shared variable 
from memory after the first synchronization point, and then to 'cache' a 
local copy of the variable, if it wishes, as long as it ensures that the variable 
is written back to memory before the second synchronization point,) 

• Each element of an array is considered to be a separate variable for the 
purpose of these rules. 

If either of these constraints is broken, the behavior of the program is undefined. 
It is up to the programmer to ensure that these constraints are met. 

Channels may be considered 'shared' in the same way that variables may be. A 
program using shared channels is valid provided that: 
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• If a process communicates on a shared channel, then the channel is not 
used for communication in the same direction by any other process at any 
time between the previous and the following synchronization points. 

• No branch of a FAR may use a channel for both input and output. 

• Each element of an array is considered to be a separate channel for the 
purpose of these rules. 

If either of these constraints is broken, the behavior of the program is undeffned. 
It is up to the programmer to ensure that these constraints are met. 

If any variable or channel which is shared is passed as an actual parameter to a 
procedure or function, then the corresponding fomnal parameter must also be 
marked as shared. Note: that this also applies across separately compiled units. 
It is up to the programmer to ensure that this is done, otherwise the behavior of the 
program is undefined. 
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